> ## 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. # List gateway spend events > Return request-level usage history for the authenticated account. Supply both UTC dates or neither; omitting both returns the previous full UTC day. Dates use a half-open range [start_date, end_date) of at most 31 days. Cost reflects budget reference rates, not invoice charges. Unknown spend is excluded and reported separately. The report snapshot supports at most 10,000 matching requests, independently of page size. Exceeding this bound returns HTTP 503 without partial results. Narrow the date range or resource filters before retrying. A failed report must not be interpreted as zero usage. Request tags can filter either report and metadata: can group the summary. ## OpenAPI ````yaml /openapi/source/external/inference/ai-gateway-spend.json get /llm_token_gateway/spend/events openapi: 3.1.0 info: title: AI Gateway Spend Reporting version: 1.0.0 description: Account-scoped request history and spend summaries for AI Gateway. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: [] tags: - name: AI Gateway description: Manage and report AI Gateway usage. paths: /llm_token_gateway/spend/events: get: tags: - AI Gateway summary: List gateway spend events description: >- Return request-level usage history for the authenticated account. Supply both UTC dates or neither; omitting both returns the previous full UTC day. Dates use a half-open range [start_date, end_date) of at most 31 days. Cost reflects budget reference rates, not invoice charges. Unknown spend is excluded and reported separately. The report snapshot supports at most 10,000 matching requests, independently of page size. Exceeding this bound returns HTTP 503 without partial results. Narrow the date range or resource filters before retrying. A failed report must not be interpreted as zero usage. Request tags can filter either report and metadata: can group the summary. operationId: get_ai_gateway_spend_events parameters: - $ref: '#/components/parameters/PageNumber' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Snapshot' - name: start_date in: query required: false schema: type: string format: date description: '' - name: end_date in: query required: false schema: type: string format: date description: '' - name: token_group_id in: query required: false schema: type: string format: uuid description: '' - name: token_user_id in: query required: false schema: type: string format: uuid description: '' - name: token_key_id in: query required: false schema: type: string format: uuid description: '' - name: end_user_id in: query required: false schema: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: '' - name: metadata in: query required: false style: deepObject explode: true schema: type: object maxProperties: 5 propertyNames: pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$ additionalProperties: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: >- Request tag filters as metadata[]=, at most 5, combined with AND. A value matches the tag's text form exactly (booleans as true/false, integers in decimal), so metadata[flag]=true matches both boolean true and the string "true". Keys are case-sensitive; reserved-prefix keys are rejected. Unindexed: bounded by the account, the date range and the report timeout. 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/SpendEvents' example: data: [] meta: page_number: 1 page_size: 20 has_more: false snapshot: 9b7e4a10-3c2d-4f5e-8a6b-1d2c3e4f5a60 '400': $ref: '#/components/responses/GatewayError400' '401': $ref: '#/components/responses/GatewayError401' '403': $ref: '#/components/responses/GatewayError403' '404': $ref: '#/components/responses/GatewayError404' '409': $ref: '#/components/responses/GatewayError409' '412': $ref: '#/components/responses/GatewayError412' '428': $ref: '#/components/responses/GatewayError428' '429': $ref: '#/components/responses/GatewayError429' '502': $ref: '#/components/responses/GatewayError502' '503': $ref: '#/components/responses/GatewayError503' '504': $ref: '#/components/responses/GatewayError504' security: - telnyxApiKey: [] components: parameters: PageNumber: name: page[number] in: query required: false schema: type: integer minimum: 1 default: 1 description: '' PageSize: name: page[size] in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: '' Snapshot: name: page[snapshot] in: query required: false schema: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: >- Required after page 1; account/filter-bound 15-minute stable snapshot; expired/mismatch 409. schemas: SpendEvents: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/SpendEvent' meta: $ref: '#/components/schemas/PageMeta' required: - data - meta SpendEvent: type: object additionalProperties: false properties: id: type: string format: uuid 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]+$ description: >- Public alias that served (the last attempt); rate_version, biller and provider_key_id follow it. requested_model: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: >- Public alias the caller requested; differs from model only when a group fallback served. attempts: type: integer minimum: 0 description: >- Provider attempts begun for the request (fallbacks included); 0 for a cache hit. Token and cost totals sum every attempt. input_tokens: anyOf: - type: integer minimum: 0 - type: 'null' output_tokens: anyOf: - type: integer minimum: 0 - type: 'null' cost: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' status: type: string enum: - succeeded - failed - partial - unknown cache_hit: type: boolean usage_status: type: string enum: - known - unknown - reconciled biller: type: string enum: - telnyx - provider - none configuration_version: type: integer minimum: 1 rate_version: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ provider_key_id: anyOf: - type: string format: uuid - type: 'null' reservation_micro_usd: type: integer minimum: 0 metadata: $ref: '#/components/schemas/RequestMetadata' required: - id - request_id - created_at - token_group_id - token_user_id - token_key_id - end_user_id - model - requested_model - attempts - input_tokens - output_tokens - cost - status - cache_hit - usage_status - biller - configuration_version - rate_version - provider_key_id - reservation_micro_usd - metadata PageMeta: type: object additionalProperties: false properties: page_number: type: integer minimum: 1 page_size: type: integer minimum: 1 maximum: 100 has_more: type: boolean snapshot: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ required: - page_number - page_size - has_more - snapshot Error: type: object additionalProperties: false properties: errors: type: array items: $ref: '#/components/schemas/ErrorItem' minItems: 1 required: - errors Money: type: number minimum: 0 maximum: 1000000000 multipleOf: 0.000001 description: >- USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting. 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 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 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 GatewayError409: description: >- The snapshot is missing, invalid, expired or does not match the account, range, filters or page size. Correct the parameters to match a valid snapshot, or restart at page[number]=1 without page[snapshot] to obtain a new snapshot. 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: >- Advisory delay in seconds. Waiting does not repair a missing, invalid, expired or mismatched snapshot. Correct the parameters to match a valid snapshot, or restart at page[number]=1 without page[snapshot]; do not replay an unchanged invalid snapshot request. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: conflict title: Snapshot conflict detail: >- Correct the parameters to match a valid snapshot, or restart at page[number]=1 without page[snapshot]. 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 GatewayError503: description: >- The report is unavailable or exceeds its bounded snapshot capacity. The report snapshot supports at most 10,000 matching requests, independently of page size. Exceeding this bound returns HTTP 503 without partial results. Narrow the date range or resource filters before retrying. A failed report must not be interpreted as zero usage. 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 an unavailable report. Narrow filters when the report exceeds its limits. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: enforcement_unavailable title: Request could not be completed detail: >- The report is unavailable or exceeds 10,000 matching requests. Narrow the date range or resource filters if the capacity limit is exceeded. 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. ````