Usage Reporting

Every inference request produces a durable spend event attributed to its token key, token user, token group and asserted end user. Two management endpoints expose that ledger:

Endpoint	Returns
`GET /spend/events`	One row per request.
`GET /spend/summary`	Totals grouped by one dimension.

Both live under https://api.telnyx.com/v2/llm_token_gateway, authenticate with the Telnyx account API key and use the same date range, filters and pagination.

Date range and filters

Parameter	Notes
`start_date`	Inclusive UTC date, `YYYY-MM-DD`. Required for `/spend/summary`.
`end_date`	Exclusive UTC date, `YYYY-MM-DD`. Required for `/spend/summary`.
`token_group_id`, `token_user_id`, `token_key_id`	Optional UUID filters.
`end_user_id`	Optional end-user identifier filter.
`group_by`	`/spend/summary` only, required: `token_group`, `token_user`, `token_key` or `end_user`.
`page[number]`, `page[size]`, `page[snapshot]`	Snapshot pagination; see below.

The range is half-open, [start_date, end_date), and spans at most 31 days. Send ISO dates, not timestamps. If you omit both dates on /spend/events, it returns the previous full UTC day. To include today, set end_date to tomorrow’s date.

Spend events

curl --globoff -G https://api.telnyx.com/v2/llm_token_gateway/spend/events \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode "start_date=2026-09-22" \
  --data-urlencode "end_date=2026-09-23" \
  --data-urlencode "token_group_id=$GROUP_ID" \
  --data-urlencode "page[size]=100"

Each event carries:

Field	Meaning
`id`, `request_id`, `created_at`	Event identity and the `X-Request-ID` of the inference request.
`token_group_id`, `token_user_id`, `token_key_id`, `end_user_id`	Attribution. `token_user_id` is null for service keys; `end_user_id` is null when the request asserted none.
`model`	The model requested.
`input_tokens`, `output_tokens`	Null when usage is unknown.
`cost`	USD at the flat reference rate used for budgets; see Budgets and billing. Null when usage is unknown.
`status`	`succeeded`, `failed`, `partial` or `unknown`.
`usage_status`	`known`, `unknown` or `reconciled` after a later correction.
`configuration_version`, `rate_version`	The policy and rate snapshot the request was valued under.
`reservation_micro_usd`	The reservation held for the request in micro-USD. It stays outstanding while usage is unknown.

Spend summary

group_by selects the dimension. Each row totals the requests attributed to one value of that dimension within the range and filters.

curl --globoff -G https://api.telnyx.com/v2/llm_token_gateway/spend/summary \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode "start_date=2026-09-01" \
  --data-urlencode "end_date=2026-10-01" \
  --data-urlencode "group_by=token_key"

{
  "data": [
    {
      "dimension_id": "9b7e4a10-3c2d-4f5e-8a6b-1d2c3e4f5a60",
      "name": "support-backend",
      "token_group_id": "5f1c9d2e-7b3a-4c8e-9f21-0a6d4e8b1c33",
      "token_user_id": null,
      "token_key_id": "9b7e4a10-3c2d-4f5e-8a6b-1d2c3e4f5a60",
      "end_user_id": null,
      "spend": 1.204311,
      "requests": 4180,
      "input_tokens": 912340,
      "output_tokens": 401277,
      "unknown_requests": 2,
      "reserved_spend": 0.0125
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 100,
    "has_more": false,
    "snapshot": "...",
    "start_date": "2026-09-01",
    "end_date": "2026-10-01",
    "group_by": "token_key"
  }
}

The four group_by dimensions are alternative views of the same requests. Do not add totals from different dimensions together.

Pagination

The first page returns meta.snapshot, a stable view bound to the account, range and filters for 15 minutes. While meta.has_more is true, request the next page[number] with the same parameters plus page[snapshot]=<meta.snapshot>. Changing filters or mixing snapshots returns 409. Treat an export as complete only once has_more is false.

Interpreting the numbers

Unknown usage is not zero. A request whose usage never arrived, for example an interrupted stream, keeps its reservation as reserved_spend and reports cost: null with usage_status: "unknown". Later reconciliation updates the same event to reconciled.
Usage is billed at standard pricing. Usage of Telnyx-hosted models is billed to your Telnyx account at standard Telnyx AI Inference pricing for each model.
BYOK requests are reported like any other. Requests on bring-your-own-key models appear in spend events and summaries like any other request. Their cost is the budget reference valuation, not a Telnyx charge; your provider bills them.
Spend is not an invoice. cost and spend are measured at a flat reference rate (USD 5 per million input tokens, USD 15 per million output tokens) for enforcing budgets and attribution. They are not your invoice.
Revoked and deleted resources keep their history. Filters by ID continue to work after a key, user or group is deleted.

AI Gateway

API

Concepts

For AI Agents

Usage Reporting

Date range and filters

Spend events

Spend summary

Interpreting the numbers

​Date range and filters

​Spend events

​Spend summary

​Pagination

​Interpreting the numbers

Date range and filters

Spend events

Spend summary

Pagination

Interpreting the numbers