> ## 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. # Export gateway usage > 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. ## OpenAPI ````yaml /openapi/source/external/inference/ai-gateway.json get /llm_token_gateway/usage/export openapi: 3.1.0 info: title: AI Gateway API version: 1.0.0 description: Account-scoped AI Gateway usage reporting. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: [] tags: - name: AI Gateway description: Manage and report AI Gateway traffic. paths: /llm_token_gateway/usage/export: get: tags: - AI Gateway summary: Export gateway usage description: >- 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. operationId: exportGatewayUsage parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 500 description: '' - name: cursor in: query required: false schema: type: string minLength: 1 maxLength: 512 pattern: ^[A-Za-z0-9_-]+$ description: >- Opaque next_cursor from a previous page; not combinable with start_time. Bound to the requested types; the account always comes from the credential. - name: start_time in: query required: false schema: type: string format: date-time description: >- First page only: RFC 3339 with offset, at most 30 days ago and not in the future; default now - 24h. - name: types in: query required: false schema: type: string pattern: ^[a-z.]+(,[a-z.]+)?$ description: >- Comma-separated subset of inference.request,guardrail.evaluation; default both. responses: '200': description: OK headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/UsageExportPage' example: data: [] meta: next_cursor: synthetic_cursor has_more: false horizon_lag_seconds: 0 '400': $ref: '#/components/responses/GatewayError400' '401': $ref: '#/components/responses/GatewayError401' '403': $ref: '#/components/responses/GatewayError403' '404': $ref: '#/components/responses/GatewayError404' '409': $ref: '#/components/responses/GatewayError40911' '412': $ref: '#/components/responses/GatewayError412' '428': $ref: '#/components/responses/GatewayError428' '429': $ref: '#/components/responses/GatewayError429' '502': $ref: '#/components/responses/GatewayError502' '503': $ref: '#/components/responses/UsageExportUnavailable' '504': $ref: '#/components/responses/GatewayError504' security: - telnyxApiKey: [] components: schemas: UsageExportPage: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/UsageExportRecord' maxItems: 1000 meta: type: object additionalProperties: false properties: next_cursor: type: string minLength: 1 maxLength: 512 pattern: ^[A-Za-z0-9_-]+$ has_more: type: boolean horizon_lag_seconds: type: integer minimum: 0 required: - next_cursor - has_more - horizon_lag_seconds required: - data - meta UsageExportRecord: oneOf: - $ref: '#/components/schemas/UsageExportInferenceRequest' - $ref: '#/components/schemas/UsageExportGuardrailEvaluation' discriminator: propertyName: type mapping: inference.request: '#/components/schemas/UsageExportInferenceRequest' guardrail.evaluation: '#/components/schemas/UsageExportGuardrailEvaluation' Error: type: object additionalProperties: false properties: errors: type: array items: $ref: '#/components/schemas/ErrorItem' minItems: 1 required: - errors UsageExportInferenceRequest: type: object additionalProperties: false properties: id: type: string pattern: ^req_[0-9a-f-]{36}_r[1-9][0-9]*$ description: 'Deterministic: req_{request_id}_r{revision}. Deduplicate on id.' type: const: inference.request schema_version: const: 1 request_id: type: string format: uuid revision: type: integer minimum: 1 supersedes: anyOf: - type: string pattern: ^req_[0-9a-f-]{36}_r[1-9][0-9]*$ - type: 'null' description: Previous revision id; keep the highest revision per request_id. timings: type: object additionalProperties: false properties: admitted_at: type: string format: date-time first_attempt_at: anyOf: - type: string format: date-time - type: 'null' completed_at: anyOf: - type: string format: date-time - type: 'null' settled_at: type: string format: date-time gateway_duration_ms: anyOf: - type: integer minimum: 0 - type: 'null' description: >- completed_at - admitted_at as recorded by the ledger; not time to first token. required: - admitted_at - first_attempt_at - completed_at - settled_at - gateway_duration_ms token_group_id: type: string format: uuid token_user_id: anyOf: - type: string format: uuid - type: 'null' token_key_id: type: string format: uuid end_user_id: anyOf: - type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ - type: 'null' model: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ provider: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ provider_model: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ route_mode: type: string enum: - managed - byok - cache protocol: type: string enum: - openai - anthropic stream: type: boolean status: type: string enum: - succeeded - failed - partial - unknown attempts: type: integer minimum: 0 input_tokens: anyOf: - type: integer minimum: 0 - type: 'null' output_tokens: anyOf: - type: integer minimum: 0 - type: 'null' usage_source: anyOf: - type: string enum: - provider - gateway_tokenizer - operator - type: 'null' usage_status: type: string enum: - known - unknown - reconciled cost: anyOf: - type: string pattern: ^((0|[1-9][0-9]{0,8})\.[0-9]{6}|1000000000\.000000)$ description: >- USD decimal string with exactly 6 places, 0 to 1000000000.000000 (the Money bound); enforcement basis, not invoice truth. - type: 'null' biller: type: string enum: - telnyx - provider - none cache_hit: type: boolean provider_key_id: anyOf: - type: string format: uuid - type: 'null' configuration_version: type: integer minimum: 1 rate_version: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ metadata: $ref: '#/components/schemas/RequestMetadata' description: Customer request tags captured at admission; {} when untagged. required: - id - type - schema_version - request_id - revision - supersedes - timings - token_group_id - token_user_id - token_key_id - end_user_id - model - provider - provider_model - route_mode - protocol - stream - status - attempts - input_tokens - output_tokens - usage_source - usage_status - cost - biller - cache_hit - provider_key_id - configuration_version - rate_version - metadata UsageExportGuardrailEvaluation: type: object additionalProperties: false properties: id: type: string pattern: ^grd_[0-9a-f-]{36}$ type: const: guardrail.evaluation schema_version: const: 1 request_id: type: string format: uuid created_at: type: string format: date-time token_group_id: type: string format: uuid token_user_id: anyOf: - type: string format: uuid - type: 'null' token_key_id: type: string format: uuid end_user_id: anyOf: - type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ - type: 'null' model: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ stage: type: string enum: - prompt - response outcome: type: string enum: - evaluated - flagged - blocked - unevaluated findings: type: array items: $ref: '#/components/schemas/GuardrailFinding' evaluation_input_tokens: anyOf: - type: integer minimum: 0 - type: 'null' evaluation_output_tokens: anyOf: - type: integer minimum: 0 - type: 'null' metadata: $ref: '#/components/schemas/RequestMetadata' required: - id - type - schema_version - request_id - created_at - token_group_id - token_user_id - token_key_id - end_user_id - model - stage - outcome - findings - evaluation_input_tokens - evaluation_output_tokens - metadata ErrorItem: type: object additionalProperties: false properties: code: type: string enum: - invalid_request - invalid_token_key - unauthorized - token_key_blocked - resource_blocked - budget_exceeded - end_user_budget_exceeded - model_not_in_catalog - rate_limit_exceeded - concurrency_limit_exceeded - not_found - conflict - idempotency_conflict - precondition_failed - precondition_required - enforcement_unavailable - upstream_error - upstream_timeout - limit_out_of_range - prompt_blocked - response_blocked - invalid_metadata - cursor_expired title: type: string detail: type: string meta: type: object additionalProperties: false properties: scope: $ref: '#/components/schemas/Scope' resets_at: anyOf: - type: string format: date-time - type: 'null' request_id: type: string format: uuid required: - request_id required: - code - title - detail - meta RequestMetadata: type: object description: >- 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 {}. maxProperties: 5 propertyNames: pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$ additionalProperties: anyOf: - type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f-\u009f]+$ - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: boolean GuardrailFinding: type: object additionalProperties: false properties: detector: type: string enum: - secrets - dlp - safety code: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ count: type: integer minimum: 0 action: type: string enum: - flag - block required: - detector - code - count - action Scope: type: string enum: - token_group - token_user - token_key - end_user responses: GatewayError400: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: invalid_request title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError401: description: Wrong/missing credential for this plane. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. WWW-Authenticate: schema: type: string description: >- Bearer challenge for this plane; no provider/master credential disclosure. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: unauthorized title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError403: description: >- Blocked/expired, exhausted budget or disallowed model; scope identifies exhausted level. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: unauthorized title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError404: description: Absent or foreign-account resource (indistinguishable). headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: not_found title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError40911: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: cursor_expired title: Request could not be completed detail: >- Restart from start_time within the retained window and deduplicate records by id. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError412: description: ETag mismatch. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: precondition_failed title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError428: description: If-Match required. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: precondition_required title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError429: description: Rate limited. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: rate_limit_exceeded title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError502: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: invalid_request title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 UsageExportUnavailable: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: >- Seconds to wait before retrying the same export read with its existing cursor or first-page parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: enforcement_unavailable title: Request could not be completed detail: The usage export page could not be completed. meta: request_id: 11111111-1111-4111-8111-111111111111 GatewayError504: description: >- 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. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated correlation ID. Cache-Control: schema: const: no-store description: All API responses; application cache is server-side only. Retry-After: schema: type: integer minimum: 1 description: Seconds; retrying inference is not idempotent. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: invalid_request title: Request could not be completed detail: Check the request and the documented handling for this error. meta: request_id: 11111111-1111-4111-8111-111111111111 securitySchemes: telnyxApiKey: type: http scheme: bearer description: Management-only Telnyx account credential. ````