> ## 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 > Return complete usage totals, UTC daily and model breakdowns, and guardrail event counts for one token group owned by the authenticated account. Requires the llm_token_gateway.usage.read permission; spend and guardrail read permissions do not grant this combined report. All sections share one database snapshot and include the latest usage corrections. Dates use an inclusive start and exclusive end spanning 1 to 31 days. Only token_group_id, start_date and end_date are accepted; pagination, group_by and other filters are rejected. Spend is reference/enforcement USD, not invoice truth or BYOK provider charges. Unknown cost is excluded from spend and reported through unknown_requests and reserved_spend. Daily rows include zero-activity days. Model rows are ordered by request count descending, then model name, and are limited to 1,000. Guardrail counts count events, not distinct requests; recent_events contains at most 20 newest events. A report that exceeds model or query limits returns 503 rather than a truncated success. ## OpenAPI ````yaml /openapi/source/external/inference/ai-gateway.json get /llm_token_gateway/usage/summary 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/summary: get: tags: - AI Gateway summary: Get gateway usage summary description: >- Return complete usage totals, UTC daily and model breakdowns, and guardrail event counts for one token group owned by the authenticated account. Requires the llm_token_gateway.usage.read permission; spend and guardrail read permissions do not grant this combined report. All sections share one database snapshot and include the latest usage corrections. Dates use an inclusive start and exclusive end spanning 1 to 31 days. Only token_group_id, start_date and end_date are accepted; pagination, group_by and other filters are rejected. Spend is reference/enforcement USD, not invoice truth or BYOK provider charges. Unknown cost is excluded from spend and reported through unknown_requests and reserved_spend. Daily rows include zero-activity days. Model rows are ordered by request count descending, then model name, and are limited to 1,000. Guardrail counts count events, not distinct requests; recent_events contains at most 20 newest events. A report that exceeds model or query limits returns 503 rather than a truncated success. operationId: gateway_usage_summary parameters: - name: token_group_id in: query required: true schema: type: string format: uuid description: ID of a token group owned by the authenticated account. example: 11111111-1111-4111-8111-111111111111 - name: start_date in: query required: true schema: type: string format: date description: >- Inclusive UTC date in YYYY-MM-DD format. Must precede end_date by 1 to 31 days. example: '2026-09-01' - name: end_date in: query required: true schema: type: string format: date description: >- Exclusive UTC date in YYYY-MM-DD format. Must follow start_date by 1 to 31 days. example: '2026-09-02' responses: '200': description: Complete usage report for the requested group and UTC date range. 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' '400': description: >- Invalid or missing query parameters, extra filters, malformed dates, or a date range outside 1 to 31 days. 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: Invalid request detail: The management request is invalid. meta: request_id: 00000000-0000-4000-8000-000000000001 '401': description: Missing or invalid Telnyx account credential. 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: Unauthorized detail: >- The supplied credentials cannot perform this management request. meta: request_id: 00000000-0000-4000-8000-000000000001 '403': description: The credential is not authorized to read the combined usage report. 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: Unauthorized detail: >- The supplied credentials cannot perform this management request. meta: request_id: 00000000-0000-4000-8000-000000000001 '404': description: The token group does not exist or belongs to another account. 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: Not found detail: The requested management resource was not found. meta: request_id: 00000000-0000-4000-8000-000000000001 '503': description: >- Reporting is unavailable, the query timed out, the report exceeds 1,000 model rows, or a USD total exceeds 1,000,000,000. No partial report is returned. 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: Delay in seconds before retrying the report. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: enforcement_unavailable title: Enforcement unavailable detail: >- A required enforcement dependency is temporarily unavailable. Retry this request. meta: request_id: 00000000-0000-4000-8000-000000000001 security: - telnyxApiKey: [] components: schemas: GatewayUsage: type: object additionalProperties: false properties: data: type: object additionalProperties: false properties: totals: $ref: '#/components/schemas/UsageMetrics' description: Metrics for all matching requests. by_day: type: array items: type: object additionalProperties: false properties: requests: type: integer minimum: 0 description: Number of matching requests. input_tokens: type: integer minimum: 0 description: >- Independently known input tokens across attempts, including corrected usage. output_tokens: type: integer minimum: 0 description: >- Independently known output tokens across attempts, including corrected usage. unknown_requests: type: integer minimum: 0 description: >- Requests whose cost remains unresolved; unknown cost is excluded from spend. cache_hits: type: integer minimum: 0 description: Requests served from the gateway cache. succeeded_requests: type: integer minimum: 0 description: Requests classified as succeeded. failed_requests: type: integer minimum: 0 description: Requests classified as failed. partial_requests: type: integer minimum: 0 description: Requests classified as partial after streaming began. spend: $ref: '#/components/schemas/Money' description: Sum of known reference/enforcement cost in USD. reserved_spend: $ref: '#/components/schemas/Money' description: Unresolved budget reservations in USD. date: type: string format: date description: UTC day. required: - requests - input_tokens - output_tokens - unknown_requests - cache_hits - succeeded_requests - failed_requests - partial_requests - spend - reserved_spend - date maxItems: 31 description: One row per UTC day, including zero-activity days. by_model: type: array items: type: object additionalProperties: false properties: requests: type: integer minimum: 0 description: Number of matching requests. input_tokens: type: integer minimum: 0 description: >- Independently known input tokens across attempts, including corrected usage. output_tokens: type: integer minimum: 0 description: >- Independently known output tokens across attempts, including corrected usage. unknown_requests: type: integer minimum: 0 description: >- Requests whose cost remains unresolved; unknown cost is excluded from spend. cache_hits: type: integer minimum: 0 description: Requests served from the gateway cache. succeeded_requests: type: integer minimum: 0 description: Requests classified as succeeded. failed_requests: type: integer minimum: 0 description: Requests classified as failed. partial_requests: type: integer minimum: 0 description: Requests classified as partial after streaming began. spend: $ref: '#/components/schemas/Money' description: Sum of known reference/enforcement cost in USD. reserved_spend: $ref: '#/components/schemas/Money' description: Unresolved budget reservations in USD. model: type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ description: Model identifier. required: - requests - input_tokens - output_tokens - unknown_requests - cache_hits - succeeded_requests - failed_requests - partial_requests - spend - reserved_spend - model maxItems: 1000 description: >- One row per model, ordered by request count descending then model name. guardrails: type: object additionalProperties: false properties: blocked_events: type: integer minimum: 0 description: Total blocked guardrail events, not distinct requests. flagged_events: type: integer minimum: 0 description: Total flagged guardrail events, not distinct requests. recent_events: type: array items: $ref: '#/components/schemas/GuardrailEvent' maxItems: 20 description: >- Up to 20 newest privacy-safe guardrail events, ordered by creation time descending and event ID. required: - blocked_events - flagged_events - recent_events description: >- Complete guardrail event counts and bounded recent findings for the same group and range. 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 required: - token_group_id - start_date - end_date required: - data - meta Error: type: object additionalProperties: false properties: errors: type: array items: $ref: '#/components/schemas/ErrorItem' minItems: 1 required: - errors UsageMetrics: type: object additionalProperties: false properties: requests: type: integer minimum: 0 description: Number of matching requests. input_tokens: type: integer minimum: 0 description: >- Independently known input tokens across attempts, including corrected usage. output_tokens: type: integer minimum: 0 description: >- Independently known output tokens across attempts, including corrected usage. unknown_requests: type: integer minimum: 0 description: >- Requests whose cost remains unresolved; unknown cost is excluded from spend. cache_hits: type: integer minimum: 0 description: Requests served from the gateway cache. succeeded_requests: type: integer minimum: 0 description: Requests classified as succeeded. failed_requests: type: integer minimum: 0 description: Requests classified as failed. partial_requests: type: integer minimum: 0 description: Requests classified as partial after streaming began. spend: $ref: '#/components/schemas/Money' description: Sum of known reference/enforcement cost in USD. reserved_spend: $ref: '#/components/schemas/Money' description: Unresolved budget reservations in USD. required: - requests - input_tokens - output_tokens - unknown_requests - cache_hits - succeeded_requests - failed_requests - partial_requests - spend - reserved_spend Money: type: number minimum: 0 multipleOf: 0.000001 description: >- Reference/enforcement USD with at most six decimal places. Not invoice truth or the BYOK provider charge. maximum: 1000000000 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]+$ description: Model identifier. 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' 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 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 - not_found - conflict - idempotency_conflict - precondition_failed - precondition_required - enforcement_unavailable - upstream_error - limit_out_of_range - prompt_blocked - response_blocked 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 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 securitySchemes: telnyxApiKey: type: http scheme: bearer description: Management-only Telnyx account credential. ````