---
title: "List gateway spend events"
method: GET
path: "/llm_token_gateway/spend/events"
tags: ["AI Gateway"]
---

# List gateway spend events

`GET /llm_token_gateway/spend/events`

## Request

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

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:<key> can group the summary.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `page[snapshot]` string
- `start_date` string, date
- `end_date` string, date
- `token_group_id` string, uuid
- `token_user_id` string, uuid
- `token_key_id` string, uuid
- `end_user_id` string
- `metadata` object

## Response `200`

OK

- SpendEvents
  - `data` SpendEvent[], 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: Public alias that served (the last attempt); rate_version, biller and provider_key_id follow it.
    - `requested_model` string, required: Public alias the caller requested; differs from model only when a group fallback served.
    - `attempts` integer, required: Provider attempts begun for the request (fallbacks included); 0 for a cache hit. Token and cost totals sum every attempt.
    - `input_tokens` integer, nullable, required
    - `output_tokens` integer, nullable, required
    - `cost` number, required: USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.
    - `status` 'succeeded' | 'failed' | 'partial' | 'unknown', required
    - `cache_hit` boolean, required
    - `usage_status` 'known' | 'unknown' | 'reconciled', required
    - `biller` 'telnyx' | 'provider' | 'none', required
    - `configuration_version` integer, required
    - `rate_version` string, required
    - `provider_key_id` string, uuid, nullable, required
    - `reservation_micro_usd` integer, 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` AiGatewaySpendPageMeta, required
    - `page_number` integer, required
    - `page_size` integer, required
    - `has_more` boolean, required
    - `snapshot` string, required

## 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`: 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.
- `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 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.
- `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/spend/events/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)