---
title: "Get gateway usage summary"
method: GET
path: "/llm_token_gateway/usage/summary"
tags: ["AI Gateway"]
---

# Get gateway usage summary

`GET /llm_token_gateway/usage/summary`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/llm_token_gateway/usage/summary`
- Auth: HTTP bearer

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.

## Query parameters

- `token_group_id` string, uuid, required
- `start_date` string, date, required
- `end_date` string, date, required
- `metadata` object

## Response `200`

OK

- GatewayUsage
  - `data` object, required
    - `totals` UsageMetrics, required
      - `requests` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `unknown_requests` integer, required
      - `cache_hits` integer, required
      - `succeeded_requests` integer, required
      - `failed_requests` integer, required
      - `partial_requests` integer, required
      - `spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
      - `reserved_spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
    - `by_day` object[], required
      - `requests` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `unknown_requests` integer, required
      - `cache_hits` integer, required
      - `succeeded_requests` integer, required
      - `failed_requests` integer, required
      - `partial_requests` integer, required
      - `spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
      - `reserved_spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
      - `date` string, date, required
    - `by_model` object[], required
      - `requests` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `unknown_requests` integer, required
      - `cache_hits` integer, required
      - `succeeded_requests` integer, required
      - `failed_requests` integer, required
      - `partial_requests` integer, required
      - `spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
      - `reserved_spend` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
      - `model` string, required
    - `guardrails` object, required
      - `blocked_events` integer, required
      - `flagged_events` integer, required
      - `recent_events` GuardrailEvent[], required
        - `record_type` 'guardrail_event', required
        - `id` string, uuid, 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
    - `token_group_id` string, uuid, required
    - `start_date` string, date, required
    - `end_date` string, date, required
    - `metadata` object, required: The metadata[<key>] filters applied to every section; {} when unfiltered.

## 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`: Membership, idempotency or snapshot conflict.
- `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 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.
- `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/summary/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)