--- title: "Export gateway usage" method: GET path: "/llm_token_gateway/usage/export" tags: ["AI Gateway"] --- # Export gateway usage `GET /llm_token_gateway/usage/export` ## Request - Base URL: `https://api.telnyx.com/v2` - URL: `https://api.telnyx.com/v2/llm_token_gateway/usage/export` - Auth: HTTP bearer Durable, replayable, content-free usage export for customer pipelines. Requires the dedicated llm_token_gateway.usage_export.read V2 action; spend.read and usage.read do not grant it. Records are inference.request (one per immutable ledger revision; a correction adds a new id with supersedes, keep the highest revision per request_id) and guardrail.evaluation (one per guardrail event, including blocked prompts with no inference record; correlate on request_id). Delivery is at least once in commit order: deduplicate on id. Records appear after settlement and after every older database transaction has finished (meta.horizon_lag_seconds); keep polling with next_cursor, which is always returned and is reusable after has_more is false. After a logical database restore, restart from start_time and deduplicate on id; a cursor from before it may return 409 cursor_expired (no Retry-After). Retention promise 30 days. No prompts, responses, provider credentials, supplier or customer rates. Gateway reference/enforcement usage, not invoice truth or BYOK provider charges. ## Query parameters - `limit` integer - `cursor` string - `start_time` string, date-time - `types` string ## Response `200` OK - UsageExportPage - `data` UsageExportRecord[], required - union - UsageExportInferenceRequest - `id` string, required: Deterministic: req_{request_id}_r{revision}. Deduplicate on id. - `type` 'inference.request', required - `schema_version` unknown, required - `request_id` string, uuid, required - `revision` integer, required - `supersedes` string, nullable, required: Previous revision id; keep the highest revision per request_id. - `timings` object, required - `admitted_at` string, date-time, required - `first_attempt_at` string, date-time, nullable, required - `completed_at` string, date-time, nullable, required - `settled_at` string, date-time, required - `gateway_duration_ms` integer, nullable, required: completed_at - admitted_at as recorded by the ledger; not time to first token. - `token_group_id` string, uuid, required - `token_user_id` string, uuid, nullable, required - `token_key_id` string, uuid, required - `end_user_id` string, nullable, required - `model` string, required - `provider` string, required - `provider_model` string, required - `route_mode` 'managed' | 'byok' | 'cache', required - `protocol` 'openai' | 'anthropic', required - `stream` boolean, required - `status` 'succeeded' | 'failed' | 'partial' | 'unknown', required - `attempts` integer, required - `input_tokens` integer, nullable, required - `output_tokens` integer, nullable, required - `usage_source` 'provider' | 'gateway_tokenizer' | 'operator', nullable, required - `usage_status` 'known' | 'unknown' | 'reconciled', required - `cost` string, nullable, required: USD decimal string with exactly 6 places, 0 to 1000000000.000000 (the Money bound); enforcement basis, not invoice truth. - `biller` 'telnyx' | 'provider' | 'none', required - `cache_hit` boolean, required - `provider_key_id` string, uuid, nullable, required - `configuration_version` integer, required - `rate_version` string, required - `metadata` RequestMetadata, required: Customer request tags from the x-ltg-metadata header: up to 5 entries. Keys are case-sensitive; keys starting with ltg_, telnyx_, litellm_ or cf_ (any case) are reserved. Values are strings (1-256 characters, no control or format characters), integers within +/-9007199254740991, or booleans; floats, null, objects and arrays are rejected. Values that look like credentials are rejected. Tags are attribution only: never forwarded upstream, never part of the response cache key, never used for budgets or routing. An untagged request reports {}. - UsageExportGuardrailEvaluation - `id` string, required - `type` 'guardrail.evaluation', required - `schema_version` unknown, required - `request_id` string, uuid, required - `created_at` string, date-time, required - `token_group_id` string, uuid, required - `token_user_id` string, uuid, nullable, required - `token_key_id` string, uuid, required - `end_user_id` string, nullable, required - `model` string, required - `stage` 'prompt' | 'response', required - `outcome` 'evaluated' | 'flagged' | 'blocked' | 'unevaluated', required - `findings` GuardrailFinding[], required - `detector` 'secrets' | 'dlp' | 'safety', required - `code` string, required - `count` integer, required - `action` 'flag' | 'block', required - `evaluation_input_tokens` integer, nullable, required - `evaluation_output_tokens` integer, nullable, required - `metadata` RequestMetadata, required: Customer request tags from the x-ltg-metadata header: up to 5 entries. Keys are case-sensitive; keys starting with ltg_, telnyx_, litellm_ or cf_ (any case) are reserved. Values are strings (1-256 characters, no control or format characters), integers within +/-9007199254740991, or booleans; floats, null, objects and arrays are rejected. Values that look like credentials are rejected. Tags are attribution only: never forwarded upstream, never part of the response cache key, never used for budgets or routing. An untagged request reports {}. - `meta` object, required - `next_cursor` string, required - `has_more` boolean, required - `horizon_lag_seconds` integer, required ## Other responses - `400`: Invalid fields, unsupported protocol options, bad page/date range (invalid_request); a well-formed token key limit of 0 or above its maximum (limit_out_of_range). prompt_blocked / response_blocked: the group guardrail policy blocked the prompt or the generated response. invalid_metadata: an authenticated inference request's x-ltg-metadata header is not a valid RequestMetadata object; the response never echoes the header. - `401`: Wrong/missing credential for this plane. - `403`: Blocked/expired, exhausted budget or disallowed model; scope identifies exhausted level. - `404`: Absent or foreign-account resource (indistinguishable). - `409`: Expired or invalidated export cursor (cursor_expired). Restart from start_time within the retained window and deduplicate records by id. Waiting and retrying the same cursor cannot recover; this response has no Retry-After header. - `412`: ETag mismatch. - `428`: If-Match required. - `429`: Rate limited. - `502`: upstream_error: every admitted provider attempt, including configured group retries and fallbacks, failed before the first provider event; streams return this real status instead of 200 plus an SSE error. Retrying is not idempotent. - `503`: The usage export is unavailable or its bounded read timed out. No partial or truncated page is returned. Preserve the current cursor and retry the same read after Retry-After; on the first page, preserve start_time and types. Do not advance the checkpoint on this error. - `504`: upstream_timeout: as 502 upstream_error, but the last admitted attempt timed out waiting for the provider (connect, read or write timeout, the attempt deadline, or x-ltg-request-timeout) before its first event. Retrying is not idempotent. ## Changes > 152 revisions in range; 1 not diffed. - **2026-10-15** `da303e40b51e`: 1 info - endpoint added [Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/llm_token_gateway/usage/export/get.md) --- [API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)