# Data pools

The shared pools your numbers draw data from: how much of each is left, and how much each member has used.

> Partner API · https://developer.telgea.com/docs/partner/api/data-pools

## The data pool object {#object}

Track the shared data pool your numbers draw on.

| Field | Type | Description |
| --- | --- | --- |
| `poolId` | string (required) | UUID of the data pool Example: `"6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34"` |
| `regionId` | string (required) | Identifier of the region this pool covers Example: `"eu-zone-1"` |
| `regionName` | string (required) | Display name of the region this pool covers Example: `"Europe"` |
| `totalAmountGB` | number (required) | Total size of the pool in GB Example: `500` |
| `consumedGB` | number (required) | Data consumed from the pool so far, in GB Example: `312.4` |
| `remainingGB` | number (required) | Data still available in the pool, in GB Example: `187.6` |
| `expirationDate` | string (required) | Date the pool expires, as an ISO date (YYYY-MM-DD) Example: `"2026-12-31"` |
| `hasActiveRestrictions` | boolean (required) | Whether any number drawing on this pool is currently restricted Example: `false` |

## Operations

- `GET` [List data pools](#list-data-pools)
- `GET` [List the members of a data pool](#list-the-members-of-a-data-pool)

### List data pools {#list-data-pools}

`GET /v1/data-pools` · Enterprise API + Partner API

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](https://developer.telgea.com/playground#tag/data-pools/GET/v1/data-pools). 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` |

**Response fields (200, ListDataPoolsResponse)**

| Field | Type | Description |
| --- | --- | --- |
| `pools` | array of DataPool (required) | Every pool your organization holds. |
| `pools.poolId` | string (required) | UUID of the data pool Example: `"6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34"` |
| `pools.regionId` | string (required) | Identifier of the region this pool covers Example: `"eu-zone-1"` |
| `pools.regionName` | string (required) | Display name of the region this pool covers Example: `"Europe"` |
| `pools.totalAmountGB` | number (required) | Total size of the pool in GB Example: `500` |
| `pools.consumedGB` | number (required) | Data consumed from the pool so far, in GB Example: `312.4` |
| `pools.remainingGB` | number (required) | Data still available in the pool, in GB Example: `187.6` |
| `pools.expirationDate` | string (required) | Date the pool expires, as an ISO date (YYYY-MM-DD) Example: `"2026-12-31"` |
| `pools.hasActiveRestrictions` | boolean (required) | Whether any number drawing on this pool is currently restricted Example: `false` |

**Example request**

```bash
curl -X GET "https://api.telgea.com/v1/data-pools" \
  -H "x-api-key: $TELGEA_API_KEY"
```

**Response 200**

```json
{
  "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 {#list-the-members-of-a-data-pool}

`GET /v1/data-pools/{poolId}/members` · Enterprise API + Partner API

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](https://developer.telgea.com/playground#tag/data-pools/GET/v1/data-pools/{poolId}/members). Calls run against your live organization; there is no sandbox.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `poolId` | path | string (uuid) (required) | UUID of the data pool Example: `6b9a0c74-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` |

**Response fields (200, ListPoolMembersResponse)**

| Field | Type | Description |
| --- | --- | --- |
| `poolId` | string (required) | UUID of the pool these members draw on. Example: `"6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34"` |
| `members` | array of PoolMember (required) | Every line drawing on this pool. |
| `members.userId` | string (required) | UUID of the user drawing on the pool Example: `"9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01"` |
| `members.msisdn` | string (required) | Phone number in E.164 format Example: `"+4520123456"` |
| `members.numberType` | enum (required) | Which line draws on the pool One of: `local`, `travel`. Example: `"local"` |
| `members.firstName` | string (required) | First name of the user holding the line, or null. Example: `"Anna"` |
| `members.lastName` | string (required) | Last name of the user holding the line, or null. Example: `"Holm"` |
| `members.email` | string (required) | Email address of the user holding the line, or null. Example: `"anna.holm@acme.example"` |
| `members.activationDate` | string (required) | Date the member joined the pool (YYYY-MM-DD) Example: `"2026-09-01"` |
| `members.terminationDate` | string (required) | Date the member left the pool (YYYY-MM-DD). Null while the line is still drawing on it. Example: `"2026-12-31"` |
| `members.usageBytes` | number (required) | 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. Example: `10485760` |

**Example request**

```bash
curl -X GET "https://api.telgea.com/v1/data-pools/6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34/members" \
  -H "x-api-key: $TELGEA_API_KEY"
```

**Response 200**

```json
{
  "poolId": "6b9a0c74-51d2-4e83-9f16-2a7c8d0e5b34",
  "members": [
    {
      "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
      "msisdn": "+4520123456",
      "numberType": "local",
      "firstName": "Anna",
      "lastName": "Holm",
      "email": "anna.holm@acme.example",
      "activationDate": "2026-09-01",
      "terminationDate": null,
      "usageBytes": 10485760
    }
  ]
}
```