Usage

The usage record object

Retrieve raw voice, SMS, and data usage records for billing and suspension.

List usage records

Returns raw voice, SMS, and data usage records for your organization whose timeStarted falls between startDate and endDate, as one feed — you do not need to know that we store calls and data separately. Records come in the order we stored or last corrected them, not by timeStarted.

Walk a period with the opaque cursor: send the first request with a startDate/endDate, then keep passing the nextCursor from each response until hasMore is false. Filter to one subscriber with userId.

Records are granular enough to bill on. Each arrives once the network reports it, from minutes to days after the usage depending on the market, and keeps its original timeStarted; a record we correct later comes round again with the same id. To poll incrementally, keep the cursor you sent for the last page and send it again, with the same window, on the next poll: you receive everything stored or corrected since, including records whose timeStarted is earlier than any you have seen. De-duplicate on id, keeping the latest copy. Records written in the last few minutes are held back until they settle. Expect usage from the last 24–48 hours to keep changing as late records arrive and are rated; the cursor delivers those updates.

Polling budget. Each API key allows 1000 requests per 24 hours, shared across every endpoint. Walk a whole organisation with the default page size rather than polling per subscriber — a request over the budget returns 429.

Requires the permission consumption:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X GET "https://api.telgea.com/v1/usage" \
  -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
}