> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Usage Reporting > Query AI Gateway spend events and dimensional summaries by group, user, key or end user, and interpret cost and unknown-usage fields correctly. 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 ```bash theme={null} 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](/docs/inference/ai-gateway/controls#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. ```bash theme={null} 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" ``` ```json theme={null} { "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]=`. 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](https://telnyx.com/pricing/inference-api) for each model. * **BYOK requests are reported like any other.** Requests on [bring-your-own-key models](/docs/inference/ai-gateway/byok) 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.