> ## 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. # Get gateway usage summary > Gateway reference/enforcement usage, not invoice truth or BYOK provider charges. Requires the dedicated llm_token_gateway.usage.read V2 action for combined spend and guardrail reporting; existing spend.read and guardrail_events.read grants do not grant this endpoint. All totals, UTC daily buckets, models and latest 20 guardrail events share one database snapshot. UTC half-open dates, at most 31 days. Zero-filled days; at most 1000 models (503 rather than truncation on overflow/timeout). Known tokens sum independently known categories across latest attempt evidence, including corrections; unknown spend is excluded and unknown_requests/reserved_spend remain explicit. Guardrail counts count events, not distinct requests. No raw spend events, prompts or secrets. This read-only report creates no pagination snapshot and accepts no pagination parameters. ## OpenAPI ````yaml /openapi/source/external/inference/ai-gateway.json get /llm_token_gateway/usage/summary openapi: 3.1.0 info: x-latency-category: responsive 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/summary: get: tags: - AI Gateway summary: Get gateway usage summary description: >- Gateway reference/enforcement usage, not invoice truth or BYOK provider charges. Requires the dedicated llm_token_gateway.usage.read V2 action for combined spend and guardrail reporting; existing spend.read and guardrail_events.read grants do not grant this endpoint. All totals, UTC daily buckets, models and latest 20 guardrail events share one database snapshot. UTC half-open dates, at most 31 days. Zero-filled days; at most 1000 models (503 rather than truncation on overflow/timeout). Known tokens sum independently known categories across latest attempt evidence, including corrections; unknown spend is excluded and unknown_requests/reserved_spend remain explicit. Guardrail counts count events, not distinct requests. No raw spend events, prompts or secrets. This read-only report creates no pagination snapshot and accepts no pagination parameters. operationId: gateway_usage_summary parameters: - name: token_group_id in: query required: true schema: type: string format: uuid description: '' - name: start_date in: query required: true schema: type: string format: date description: '' - name: end_date in: query required: true schema: type: string format: date 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/GatewayUsage' example: data: totals: requests: 2 input_tokens: 120 output_tokens: 30 unknown_requests: 1 cache_hits: 0 succeeded_requests: 1 failed_requests: 0 partial_requests: 0 spend: 0.00045 reserved_spend: 0.01 by_day: - date: '2026-09-01' requests: 2 input_tokens: 120 output_tokens: 30 unknown_requests: 1 cache_hits: 0 succeeded_requests: 1 failed_requests: 0 partial_requests: 0 spend: 0.00045 reserved_spend: 0.01 by_model: - model: Qwen/Qwen3-235B-A22B requests: 2 input_tokens: 120 output_tokens: 30 unknown_requests: 1 cache_hits: 0 succeeded_requests: 1 failed_requests: 0 partial_requests: 0 spend: 0.00045 reserved_spend: 0.01 guardrails: blocked_events: 0 flagged_events: 0 recent_events: [] meta: token_group_id: 11111111-1111-4111-8111-111111111111 start_date: '2026-09-01' end_date: '2026-09-02' metadata: {} '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/UsageSummaryUnavailable' '504': $ref: '#/components/responses/GatewayError504' security: - telnyxApiKey: [] x-codeSamples: - lang: JavaScript source: >- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const response = await client.llmTokenGateway.usage.retrieveSummary(); console.log(response.data); - lang: Python source: | import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) response = client.llm_token_gateway.usage.retrieve_summary() print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.LlmTokenGateway.Usage.GetSummary(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); var response = client.llmTokenGateway().usage().retrieveSummary(); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.llm_token_gateway.usage.retrieve_summary puts(response) - lang: PHP source: >- llmTokenGateway->usage->retrieveSummary(); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx llm-token-gateway:usage retrieve-summary \ --api-key 'My API Key' components: schemas: GatewayUsage: type: object additionalProperties: false properties: data: type: object additionalProperties: false properties: totals: $ref: '#/components/schemas/UsageMetrics' by_day: type: array items: type: object additionalProperties: false properties: requests: type: integer minimum: 0 input_tokens: type: integer minimum: 0 output_tokens: type: integer minimum: 0 unknown_requests: type: integer minimum: 0 cache_hits: type: integer minimum: 0 succeeded_requests: type: integer minimum: 0 failed_requests: type: integer minimum: 0 partial_requests: type: integer minimum: 0 spend: $ref: '#/components/schemas/Money' reserved_spend: $ref: '#/components/schemas/Money' date: type: string format: date required: - requests - input_tokens - output_tokens - unknown_requests - cache_hits - succeeded_requests - failed_requests - partial_requests - spend - reserved_spend - date maxItems: 31 by_model: type: array items: type: object additionalProperties: false properties: requests: type: integer minimum: 0 input_tokens: type: integer minimum: 0 output_tokens: type: integer minimum: 0 unknown_requests: type: integer minimum: 0 cache_hits: type: integer minimum: 0 succeeded_requests: type: integer minimum: 0 failed_requests: type: integer minimum: 0 partial_requests: type: integer minimum: 0 spend: $ref: '#/components/schemas/Money' reserved_spend: $ref: '#/components/schemas/Money' model: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ required: - requests - input_tokens - output_tokens - unknown_requests - cache_hits - succeeded_requests - failed_requests - partial_requests - spend - reserved_spend - model maxItems: 1000 guardrails: type: object additionalProperties: false properties: blocked_events: type: integer minimum: 0 flagged_events: type: integer minimum: 0 recent_events: type: array items: $ref: '#/components/schemas/GuardrailEvent' maxItems: 20 required: - blocked_events - flagged_events - recent_events required: - totals - by_day - by_model - guardrails meta: type: object additionalProperties: false properties: token_group_id: type: string format: uuid start_date: type: string format: date end_date: type: string format: date metadata: type: object description: >- The metadata[] filters applied to every section; {} when unfiltered. 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]+$ required: - token_group_id - start_date - end_date - metadata required: - data - meta UsageMetrics: type: object additionalProperties: false properties: requests: type: integer minimum: 0 input_tokens: type: integer minimum: 0 output_tokens: type: integer minimum: 0 unknown_requests: type: integer minimum: 0 cache_hits: type: integer minimum: 0 succeeded_requests: type: integer minimum: 0 failed_requests: type: integer minimum: 0 partial_requests: type: integer minimum: 0 spend: $ref: '#/components/schemas/Money' reserved_spend: $ref: '#/components/schemas/Money' required: - requests - input_tokens - output_tokens - unknown_requests - cache_hits - succeeded_requests - failed_requests - partial_requests - spend - reserved_spend 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. GuardrailEvent: type: object additionalProperties: false properties: record_type: const: guardrail_event 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]+$ 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: - record_type - id - 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 Error: type: object additionalProperties: false properties: errors: type: array items: $ref: '#/components/schemas/ErrorItem' minItems: 1 required: - errors 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 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: Membership, idempotency or snapshot conflict. 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: idempotency_conflict 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 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 UsageSummaryUnavailable: description: >- The usage report is unavailable, its query timed out, or it exceeds the 1,000-model-row limit. No partial or truncated report is returned. Honor Retry-After for a temporary failure. If the report exceeds its limits, narrow the UTC date range or add metadata filters before retrying. Treat unavailable totals as unknown, not zero. 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 the date range or add metadata filters if 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 usage report 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. ````