Data pools
The shared pools your numbers draw data from: how much of each is left, and how much each member has used.
The data pool object
Track the shared data pool your numbers draw on.
| Field | Type | Description |
|---|---|---|
poolIdrequired | string | UUID of the data pool6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34 |
regionIdrequired | string | Identifier of the region this pool coverseu-zone-1 |
regionNamerequired | string | Display name of the region this pool coversEurope |
totalAmountGBrequired | number | Total size of the pool in GB500 |
consumedGBrequired | number | Data consumed from the pool so far, in GB312.4 |
remainingGBrequired | number | Data still available in the pool, in GB187.6 |
expirationDaterequired | string | Date the pool expires, as an ISO date (YYYY-MM-DD)2026-12-31 |
hasActiveRestrictionsrequired | boolean | Whether any number drawing on this pool is currently restrictedfalse |
Operations
List data pools
Retrieves every active data pool in your organization, with how much of each is left.
A pool covers one region. Numbers in that region draw on the pool as they use data, and stop when it is exhausted — so remainingGB is the figure to watch if you resell the pool and decide when to top up or throttle a customer.
Consumption figures lag the network by the same delay as the usage feed, up to about 16 hours in some markets, so remainingGB does not yet count usage the network has not reported.
Scope: pools:read.
Requires the permission pools:read on the key.
Try it in the playground → Calls run against your live organization; there is no sandbox.
Responses
| Status | Meaning | Body |
|---|---|---|
200 | Successfully retrieved the active data pools and their balances. | ListDataPoolsResponse |
400 | Request failed schema validation, or was refused by a business rule | none |
401 | Missing or invalid API key in the X-API-Key header | UnauthorizedError |
403 | Insufficient permissions to view data pools | ForbiddenError |
429 | The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets. | TooManyRequestsError |
500 | Internal server error. Contact support if this persists. | InternalError |
Problems this endpoint can return
This endpoint returns no domain-specific problems.
Response fields
200 ListDataPoolsResponse
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
poolsrequired | array of DataPool | Every pool your organization holds. | |||||||||||||||||||||||||||
Show 8 child fields of | |||||||||||||||||||||||||||||
| Field | Type | Description |
|---|---|---|
poolIdrequired | string | UUID of the data pool6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34 |
regionIdrequired | string | Identifier of the region this pool coverseu-zone-1 |
regionNamerequired | string | Display name of the region this pool coversEurope |
totalAmountGBrequired | number | Total size of the pool in GB500 |
consumedGBrequired | number | Data consumed from the pool so far, in GB312.4 |
remainingGBrequired | number | Data still available in the pool, in GB187.6 |
expirationDaterequired | string | Date the pool expires, as an ISO date (YYYY-MM-DD)2026-12-31 |
hasActiveRestrictionsrequired | boolean | Whether any number drawing on this pool is currently restrictedfalse |
/v1/data-poolsRequest
curl -X GET "https://api.telgea.com/v1/data-pools" \
-H "x-api-key: $TELGEA_API_KEY"Response
{
"pools": [
{
"poolId": "6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34",
"regionId": "eu-zone-1",
"regionName": "Europe",
"totalAmountGB": 500,
"consumedGB": 312.4,
"remainingGB": 187.6,
"expirationDate": "2026-12-31",
"hasActiveRestrictions": false
}
]
}List the members of a data pool
Retrieves every user drawing on a data pool, with the data each has taken from it.
Use this to attribute a pool's consumption to individual customers. usageBytes is the member's usage across all their lines, repeated on each of their rows, so count it once per userId rather than summing the rows.
A pool belonging to another organization answers 404, not 403.
Scope: pools:read.
Requires the permission pools:read on the key.
Try it in the playground → Calls run against your live organization; there is no sandbox.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
poolIdrequired | path | string (uuid) | UUID of the data pool6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34 |
Responses
| Status | Meaning | Body |
|---|---|---|
200 | Successfully retrieved the pool members and their usage. | ListPoolMembersResponse |
400 | Request failed schema validation, or was refused by a business rule | none |
401 | Missing or invalid API key in the X-API-Key header | UnauthorizedError |
403 | Insufficient permissions to view data pools | ForbiddenError |
404 | No data pool in your organization has this id | NotFoundError |
429 | The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets. | TooManyRequestsError |
500 | Internal server error. Contact support if this persists. | InternalError |
Problems this endpoint can return
| Status | Problem | When |
|---|---|---|
404 | Pool not found | A request names a data pool that your organization does not have. |
Response fields
200 ListPoolMembersResponse
| Field | Type | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
poolIdrequired | string | UUID of the pool these members draw on.6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34 | ||||||||||||||||||||||||||||||
membersrequired | array of PoolMember | Every line drawing on this pool. | ||||||||||||||||||||||||||||||
Show 9 child fields of | ||||||||||||||||||||||||||||||||
| Field | Type | Description |
|---|---|---|
userIdrequired | string | UUID of the user drawing on the pool9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01 |
msisdnrequired | string | Phone number in E.164 format+4520123456 |
numberTyperequired | enumlocaltravel | Which line draws on the poollocal |
firstNamerequired | string | First name of the user holding the line, or null.Anna |
lastNamerequired | string | Last name of the user holding the line, or null.Holm |
emailrequired | string | Email address of the user holding the line, or null. |
activationDaterequired | string | Date the member joined the pool (YYYY-MM-DD)2026-09-01 |
terminationDaterequired | string | Date the member left the pool (YYYY-MM-DD). Null while the line is still drawing on it.2026-12-31 |
usageBytesrequired | number | Bytes the member has drawn from the pool across all their lines. A member with several lines is listed once per line, each row carrying the same total, so add it once per userId.10485760 |
/v1/data-pools/{poolId}/membersRequest
curl -X GET "https://api.telgea.com/v1/data-pools/6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34/members" \
-H "x-api-key: $TELGEA_API_KEY"Response
{
"poolId": "6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34",
"members": [
{
"userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
"msisdn": "+4520123456",
"numberType": "local",
"firstName": "Anna",
"lastName": "Holm",
"email": "[email protected]",
"activationDate": "2026-09-01",
"terminationDate": null,
"usageBytes": 10485760
}
]
}