Usage

Query the per-request usage ledger for the authenticated API customer.

Returns the per-request rows the router writes to the usage ledger every time the calling customer makes a successful API request. Use it to audit consumption, attribute spend to specific API keys, or reconcile against an internal billing system.

The same data drives the Usage page in the console dashboard — the API exposes it for programmatic access.

`GET /v1/usage`

Returns paginated usage rows for the calling API key's customer, newest first.

Headers

Header	Notes
`Authorization`	`Bearer tr-…` API key. Required.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`100`	Page size. Maximum `1000`.
`offset`	integer	`0`	Number of rows to skip (newest-first ordering).
`start`	string	—	RFC3339 timestamp. Only return rows with `created_at >= start`.
`end`	string	—	RFC3339 timestamp. Only return rows with `created_at <= end`.
`model`	string	—	Exact match on the routed model ID (e.g. `global/redpill/gpt-oss-120b`).
`key_prefix`	string	—	Filter by the customer-visible API-key prefix (e.g. `tr-live-a1b2c3d4`). Useful when attributing per-key spend.

Example request

curl "https://api.tresor.co/v1/usage?limit=50&model=global/redpill/gpt-oss-120b" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK with Content-Type: application/json:

{
  "data": [
    {
      "id": "8a1b3f4c-2d6e-4f9a-9c5b-1e7d8a0c4b2f",
      "model": "global/redpill/gpt-oss-120b",
      "modality": "chat",
      "provider": "redpill",
      "region": "global",
      "billing_unit": "token",
      "audio_seconds": null,
      "prompt_tokens": 42,
      "completion_tokens": 128,
      "cost_eur": 0.000182,
      "discount_applied_pct": 0,
      "receipt_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "failover": false,
      "key_prefix": "tr-live-a1b2c3d4",
      "key_name": "Default",
      "created_at": "2026-05-06T10:52:02Z"
    }
  ],
  "total_count": 1234,
  "limit": 50,
  "offset": 0
}

Field	Type	Description
`id`	string	Stable ledger row ID (UUID v4).
`model`	string	Routed model ID for this request.
`modality`	string	Request modality: `chat`, `transcription`, or `embedding`.
`provider`	string	Upstream provider that served the request (e.g. `redpill`, `tinfoil`, `chutes`, `privatemode`).
`region`	string	Provider region tag, when applicable. Omitted for region-less providers.
`billing_unit`	string	Billing unit for this row, such as `token`, `audio_minute`, `audio_second`, or `request`.
`audio_seconds`	number \| `null`	Duration metadata recorded for transcription requests when available. `null` when the provider does not return a duration.
`prompt_tokens`	integer	Tokens billed for the input prompt.
`completion_tokens`	integer	Tokens billed for the generated completion.
`cost_eur`	number	Net amount billed in EUR for this request, after any plan discount.
`discount_applied_pct`	integer	Percentage discount applied (e.g. `10` for a 10 % included-tier discount, `0` for pay-as-you-go).
`receipt_id`	string \| `null`	The corresponding receipt ID, or `null` if the caller opted out via `X-Tresor-Receipt: false`. Fetch the JWS via `GET /v1/receipts/{id}`.
`failover`	boolean	`true` if routing failover moved the request from the preferred route to a secondary route.
`key_prefix`	string \| `null`	Non-secret prefix of the API key that issued the request (matches what's shown in the dashboard). `null` if the key was deleted.
`key_name`	string \| `null`	Operator-set name of the API key. `null` if the key was deleted.
`total_count`	integer	Total number of rows matching the filter (across all pages).
`limit` / `offset`	integer	Echo of the pagination parameters.

Pagination

Rows are returned newest-first. To page, increase offset by limit until data comes back empty or shorter than limit. For long ranges, prefer narrowing with start / end over deep paging.

Errors

Status	`code`	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`500`	`internal`	Failed to query the ledger. Retry after a delay.
`503`	`service_unavailable`	Usage data is temporarily unavailable.

Error bodies follow the standard error envelope.