Monitor usage

Three endpoints tell you what your lines use, each for a different job:

Usage appears once the network has reported it, which takes from minutes to most of a day depending on the market, so the most recent traffic may not be in any of them yet. See how late usage arrives.

Read the usage feed

GET /v1/usage returns voice, SMS and data records for your whole organization as one feed, in the order we stored or last corrected them. Ask for a window of at most 31 days, then follow the cursor until hasMore is false:

curl "https://api.telgea.com/v1/usage?startDate=2026-09-01&endDate=2026-09-30" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "items": [
    {
      "id": "cdr_01j9v2k8f3m4n5p6q7r8s9t0u1",
      "type": "DATA",
      "provider": "telia-denmark",
      "msisdn": "+4520123456",
      "timeStarted": "2026-09-11T08:30:00.000Z",
      "timeEnded": "2026-09-11T08:34:12.000Z",
      "amount": 10485760,
      "unit": "bytes",
      "servingCountryCode": "DK",
      "usageClass": "domestic",
      "counterpartyMsisdn": null,
      "callDirection": null,
      "counterpartyCountryCode": null,
      "networkType": "5G",
      "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
      "date": "2026-09-11",
      "totalPrice": "0.043200",
      "unitPrice": "0.004320",
      "currency": "EUR",
      "rateId": "rate_01j9v2k8f3m4n5p6q7r8s9t0u1"
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0wOS0xMVQwODozMDowMC4xMjM0NTZaIiwicyI6ImRhdGEiLCJpIjoiY2RyXzEifQ",
  "hasMore": true
}

Pass nextCursor back as cursor for the next page. Each record's id is stable, so you can de-duplicate across reads. Records written in the last few minutes are held back until they settle.

• amount is counted in unit: seconds for voice, a count for messages, bytes for data.
• userId names the end-user; filter to one with the userId query parameter.
• totalPrice is a decimal string. It is null until the record is rated, and on usage covered by a data pool.

Mind the polling budget. Each API key allows 1000 requests per 24 hours, shared across every endpoint. Walk the whole organization with the default page size rather than polling per customer.

How late usage arrives

Each network reports usage on its own schedule. Typical delay between the usage and its record reaching the feed:

A record also stays out of the feed until it has been matched to your organization, which happens hourly.

Treat usage from the last 24–48 hours as still filling in: most records arrive and are rated within that time, and any that arrive or change later still reach you through the cursor.

A late record keeps its original timeStarted, so it lands in a period you may already have read. You still receive it: once hasMore is false, keep the cursor you sent for that last page and send it again, with the same window, on your next poll. You get every record in that window stored or corrected since, including late ones and records whose totalPrice has since been rated. A corrected record comes again with the same id; keep the latest copy.

The same delay applies to analytics and to data pool consumption: remainingGB does not yet count usage the network has not reported.

Chart consumption with analytics

GET /v1/analytics returns the same consumption already totalled per interval (day or month), with the highest, lowest and average interval across the window. Narrow it with userId, msisdn or countryIsoCode. Use it for dashboards and reports; use the feed when you need individual records.

Watch a data pool

Numbers in a region draw on that region's shared pool as they use data, and stop when it is exhausted. GET /v1/data-pools lists every active pool with what is left:

{
  "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
    }
  ]
}

remainingGB is the figure to watch. To attribute a pool's consumption to individual customers, list its members: each carries usageBytes, the data that member has drawn from the pool across all their lines. A member with several lines appears once per line with the same usageBytes on each row, so count it once per userId rather than summing the rows.