All paths are relative to
https://api.telnyx.com/v2/llm_token_gateway and authenticate with the Telnyx account API key.
Group usage report
Use Get gateway usage summary to build a group dashboard without fetching individual request pages. Each response uses one database snapshot and reflects the latest available usage corrections. The credential needs thellm_token_gateway.usage.read permission for this combined report. Existing spend and guardrail permissions do not grant access to it.
The endpoint requires token_group_id, start_date and end_date and accepts optional metadata[<key>] filters. The group must belong to the authenticated account. Dates are UTC YYYY-MM-DD, with an inclusive start and exclusive end, spanning 1 to 31 days. Pagination parameters, group_by and other filters are not accepted. Tag filters apply to every report section and are echoed in meta.metadata.
Each metric row contains
requests, input_tokens, output_tokens, spend, reserved_spend, unknown_requests, cache_hits, succeeded_requests, failed_requests and partial_requests. Known input and output tokens are counted independently, including when the other token category remains unknown. Unknown cost is excluded from spend; reserved_spend reports the unresolved budget hold in USD.
Totals, daily rows and model rows are alternative views of the same requests. Do not add the sections together. The report includes up to 1,000 model rows and returns HTTP 503 if the report cannot be completed within its limits; it never returns a silently truncated success. A failed report must not be displayed as zero usage.
The spend endpoints below retain their separate filters and snapshot pagination.
Date range and filters
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
Spend summary
group_by selects the dimension. Each row totals the requests attributed to one value of that dimension within the range and filters.
group_by dimensions are alternative views of the same requests. Do not add totals from different dimensions together.
Request tags
Attach up to five attribution tags to an inference request using thex-ltg-metadata header. Send one JSON object, at most 2,048 ASCII bytes; encode non-ASCII characters as JSON Unicode escapes.
[A-Za-z0-9][A-Za-z0-9_.-]*. Prefixes ltg_, telnyx_, litellm_ and cf_ are reserved regardless of case. Values are non-empty strings of at most 256 characters without control/format characters, integers from -9,007,199,254,740,991 to 9,007,199,254,740,991, or booleans. Floats, null, arrays, objects and credential-like values are rejected with 400 invalid_metadata; the error never echoes the header. Use non-sensitive attribution labels.
Tags do not configure budgets or routing. They are never forwarded upstream, do not affect cache identity and are not echoed by inference responses. They appear on spend events, guardrail events and usage-summary recent events, including the current request’s tags on cache hits. They are separate from the Anthropic body field metadata.user_id; OpenAI body metadata is not accepted.
Filter /spend/events, /spend/summary, /guardrail_events or /usage/summary with metadata[team]=support. At most five filters are combined with AND and match exact text: booleans use true/false, integers decimal text. Consequently a filter value true matches both boolean true and the string "true". Keep the same filters when paging a snapshot.
Use /spend/summary?group_by=metadata:team to group by a tag’s text value. Requests missing the tag form a row with dimension_id: null. Tags do not create portal-wide defaults: applications supply them on each request.
Durable usage export
Export gateway usage returns content-freeinference.request and guardrail.evaluation records. It requires the separate llm_token_gateway.usage_export.read permission; spend/report permissions do not grant it. This is a pull API; no push destination is configured on a gateway.
Persist records in your sink before saving
meta.next_cursor. Deduplicate on record id: delivery is at least once. A corrected inference record has a higher revision and a supersedes link; retain the highest revision per request_id. Join guardrail records on request_id. Both record types include captured request tags in metadata, or {} for an untagged request. Persist these tags with the record for attribution.
While meta.has_more is true, fetch the next page immediately. When false, keep the cursor and poll later; an empty page does not end the feed. meta.horizon_lag_seconds reports delayed visibility of committed records. Retention is guaranteed for 30 days.
On 409 cursor_expired, restart from a start_time within the retained window and deduplicate. A notified logical restore also requires this restart even if an old cursor is still accepted. On 503 enforcement_unavailable, preserve the cursor and honor Retry-After; the endpoint returns an error instead of partial or truncated data. Unknown usage and reference spend retain the same caveats as other reports; this export is not invoice truth.
Report limits
Each spend report includes at most 10,000 matching requests, regardless of the requested page size. A report that exceeds this limit returns HTTP 503 instead of partial totals. Reduce the date range or narrow the resource filters before retrying; reducing the page size does not reduce the work needed to create the report snapshot. Treat a failed or timed-out report as unavailable; do not replace its totals with zero.Pagination
The first page returnsmeta.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.
On a snapshot 409, correct the parameters to match the original valid snapshot, or restart with page[number]=1 and omit page[snapshot] to obtain a new snapshot. The response carries Retry-After, but waiting does not make an invalid or expired snapshot usable. When restarting, discard the earlier pages; do not combine pages from different snapshots in one export.
Interpreting the numbers
- Unknown usage is not zero. A request whose usage never arrived, for example an interrupted stream, keeps its reservation as
reserved_spendand reportscost: nullwithusage_status: "unknown". Later reconciliation updates the same event toreconciled. - 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
costis the budget reference valuation, not a Telnyx charge; your provider bills them. - Spend is not an invoice.
costandspendare 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.