# List session generations

Requests with the same session ID, sent in the `x-session-id` header or the `session_id`
field of a chat completion (the field wins if both are set, as on OpenRouter), form a
session, for example a conversation or an agent run. This lists their generations in the
order the requests arrived, each with model, provider, tokens, cost in EUR and timing as in
`GET /v1/generation`. Never prompts or answers.

Only keys of the same organization and workspace that sent the requests see a session; for every other key it
does not exist. This gateway instance keeps the most recent generations in memory, so older
ones are missing, and at most the 500 most recent generations of a session are listed
(`total` says how many are kept).

`GET https://api.tokenlane.de/v1/sessions/{id}`

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "API key as bearer token in the `Authorization` header: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Missing, unknown or expired keys get 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

Values starting with YOUR_ are placeholders. Replace them with appropriate values before sending.

## curl

```curl
curl --request GET \
  --url 'https://api.tokenlane.de/v1/sessions/YOUR_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## node

```node
const response = await fetch("https://api.tokenlane.de/v1/sessions/YOUR_ID", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
  },
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/sessions/YOUR_ID",
    method="GET",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
    },
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/sessions/YOUR_ID", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
  },
});
console.log(await response.text());
```

## path: id (required)

The session ID: 1 to 256 characters from letters, digits, `-`, `_`, `.` and `:`

### s7: string

{}

## Response 200: application/json

The session's generations, oldest first; amounts in EUR

```json
{
  "data": {
    "generations": [],
    "session_id": "support-chat-4711",
    "total": 2
  }
}
```

### s35: object

Response of `GET /v1/sessions/{id}`.

{}

- data (required): s396

### s396: object

The session and its generations.

{}

```json
{
  "generations": [],
  "session_id": "support-chat-4711",
  "total": 2
}
```

- generations (required): s986

### s986: array

The generations, oldest first, each in the format of `GET /v1/generation` (at most the
500 most recent).

{}

### s136: object

What the gateway recorded about one generation: model, provider, tokens, cost, timing and
how it ended. Never the prompt or the answer.

Differences from OpenRouter: `total_cost`, `usage` and `upstream_inference_cost` are in
**EUR** (see `currency`). Token counts are the provider's own (`tokens_*` equal
`native_tokens_*`). Fields for features the gateway does not have (apps, presets, BYOK,
web fetch, moderation, media counts, caching discounts) are null or fixed, as named in
each field. `upstream_inference_cost` is the token cost alone; `total_cost` adds server
tools such as web search. Additional fields: `currency`, `original`, `requested_model`,
`first_byte_latency`, `error_type`, `parent_id`, `num_web_searches` and the time
breakdown `gateway_overhead`, `queue_time` and `timings`.

A generation appears once it has ended (answered, failed or cancelled by the client), and
before the last byte of its answer is sent.

{}

```json
{
  "api_type": "completions",
  "app_id": null,
  "cache_discount": null,
  "cancelled": false,
  "created_at": "2026-10-19T08:15:42.118Z",
  "currency": "EUR",
  "data_region": "europe",
  "error_type": null,
  "external_user": null,
  "finish_reason": "stop",
  "first_byte_latency": 310,
  "gateway_overhead": 0.412,
  "generation_time": 1180,
  "http_referer": null,
  "id": "gen-01k7tm9qz3f5c8x2v6b4n0m7hd",
  "is_byok": false,
  "latency": 1250,
  "model": "deepseek/deepseek-v4.1-flash",
  "moderation_latency": null,
  "native_finish_reason": "stop",
  "native_tokens_cached": 0,
  "native_tokens_completion": 25,
  "native_tokens_completion_images": null,
  "native_tokens_prompt": 10,
  "native_tokens_reasoning": 5,
  "num_fetches": null,
  "num_input_audio_prompt": null,
  "num_media_completion": null,
  "num_media_prompt": null,
  "num_search_results": null,
  "num_web_searches": 0,
  "ocr_cost": 0,
  "origin": "",
  "original": null,
  "parent_id": null,
  "preset_id": null,
  "provider_name": "scaleway",
  "provider_responses": null,
  "queue_time": 0,
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "requested_model": "eu/fast",
  "router": "eu/fast",
  "service_tier": null,
  "session_id": null,
  "streamed": true,
  "timings": {
    "auth": 0.081,
    "body": 0.034,
    "post": 0.079,
    "queue": 0,
    "routing": 0.096,
    "streaming": 940.374,
    "total": 1250,
    "upstream": 309.214,
    "validate": 0.122
  },
  "tokens_completion": 25,
  "tokens_prompt": 10,
  "total_cost": 0.000021,
  "upstream_id": "chatcmpl-791bcf62-080e-4568-87d0-94c72e3b4946",
  "upstream_inference_cost": 0.000021,
  "usage": 0.000021,
  "user_agent": null,
  "web_search_engine": null,
  "workspace_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- api_type (required): s694

### s694: string | null

Which API created the generation: `completions` for chat completions, `responses`
for the Responses API, `embeddings`
for embeddings, `stt` for audio transcriptions, `rerank` for document ranking,
and `decisions` for structured decisions.

{}

```json
"completions"
```

- app_id (required): s695

### s695: integer | null

ID of the app that sent the request. Always null: apps are not tracked.

int64

{}

- app_title (optional): s696

### s696: string | null

Caller-supplied application title (X-OpenRouter-Title, then X-Title), or null.

{}

```json
"Example client"
```

- attribution_truncated (optional): s697

### s697: boolean

Attribution exceeded its 4096-byte text budget or the process-wide 16-MiB memory
budget. Fields may be shortened or absent; billing metadata is always retained.

{}

```json
false
```

- byok_fallback (optional): s698

### s698: boolean | null

An authorized fallback from a customer credential to platform credit occurred.

{}

```json
true
```

- byok_fee (optional): s699

### s699: object

Tokenlane's service fee for requests that used the organization's own provider
credentials (not part of OpenRouter's format); absent for platform-funded requests.

{}

```json
{
  "estimated_tokens": 0,
  "fee": 0.00005,
  "free": false,
  "free_requests": 100000,
  "reported_tokens": 1480,
  "request_number": 100001,
  "tokens": 1480
}
```

- estimated_tokens (required): s502

### s502: integer

The part of `tokens` estimated by the gateway.

int64

{"minimum":"0"}

```json
0
```

- fee (required): s503

### s503: number

The fee debited for this request. The monthly total of billable tokens is rounded
down to whole thousands, so a single request can be charged less than its tokens imply.

double

{}

```json
0.00005
```

- free (required): s504

### s504: boolean

Whether the request was inside the free allowance.

{}

- free_requests (required): s505

### s505: integer

Free requests per customer identity and month.

int64

{"minimum":"0"}

```json
100000
```

- reported_tokens (required): s506

### s506: integer

The part of `tokens` taken from the provider's reported usage.

int64

{"minimum":"0"}

```json
1480
```

- request_number (required): s507

### s507: integer

One-based number of this request within the customer identity's UTC calendar month.

int64

{"minimum":"0"}

```json
100001
```

- tokens (required): s508

### s508: integer

Tokens counted for this request: the provider's usage for curated providers, the
gateway's own deterministic estimate for customer-defined endpoints.

int64

{"minimum":"0"}

```json
1480
```

- byok_fee_pending (optional): s700

### s700: boolean | null

The service fee is awaiting the same durable financial operation as its reservation.
While true, total_cost includes only confirmed base charges, not an assumed zero fee.

{}

```json
true
```

- cache_discount (required): s701

### s701: number | null

Discount from prompt caching. Always null: not calculated.

double

{}

- cancelled (required): s702

### s702: boolean | null

Whether the client closed the connection before the answer was complete.

{}

```json
false
```

- cost_details (required): s703

### s703: object | null

Disjoint monetary line items in the declared currency. Their exact sum is the cost;
aggregate fields such as upstream_inference_cost must not be added a second time.

{}

```json
{
  "cache_read_cost": 0.000001,
  "cache_write_cost": 0,
  "completion_cost": 0.00002,
  "currency": "EUR",
  "media_cost": 0,
  "ocr_cost": 0,
  "prompt_cost": 0.00001,
  "reasoning_cost": 0,
  "request_cost": 0.001,
  "server_tool_cost": 0
}
```

- cache_read_cost (required): s572

### s572: number

Input tokens read from cache, including cached audio.

double

{}

```json
0.00001
```

- cache_write_cost (required): s573

### s573: number

Input tokens written to cache, including extended TTLs.

double

{}

```json
0.00001
```

- completion_cost (required): s574

### s574: number

Ordinary output tokens, excluding reasoning and audio.

double

{}

```json
0.00001
```

- currency (required): s575

### s575: string

ISO 4217 currency for every line item; EUR for customer-facing costs.

{}

```json
"EUR"
```

- media_cost (required): s576

### s576: number

Input/output media tokens, image fees and transcribed seconds.

double

{}

```json
0.00001
```

- ocr_cost (required): s577

### s577: number

Shared OCR preprocessing, charged once per generation and zero for provider expenses.

double

{}

```json
0.00001
```

- pii_cost (optional): s578

### s578: number | null

Shared PII detection charge in EUR, included once in the customer total.

double

{}

```json
0.000002
```

- prompt_cost (required): s579

### s579: number

Uncached ordinary input tokens.

double

{}

```json
0.00001
```

- reasoning_cost (required): s580

### s580: number

Internal reasoning tokens.

double

{}

```json
0.00001
```

- request_cost (required): s581

### s581: number

Fixed upstream request fee.

double

{}

```json
0.00001
```

- server_tool_cost (required): s582

### s582: number

Native server tools, including web search.

double

{}

```json
0.00001
```

- created_at (required): s704

### s704: string

When the gateway received the request, RFC 3339 in UTC.

date-time

{}

```json
"2026-10-19T08:15:42.118Z"
```

- currency (required): s705

### s705: string

Currency of `total_cost`, `usage` and `upstream_inference_cost`: always `EUR`.

{}

```json
"EUR"
```

- data_region (required): s706

### s706: string

Where the generation was processed: always `europe`.

"global", "europe"

{}

- error_type (optional): s707

### s707: string | null

Error type in `error.metadata.type`, stable for programs. "Errors" in the introduction
lists the HTTP status and what to do for each.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal", null

{}

```json
"invalid_parameter"
```

- external_user (required): s708

### s708: string | null

The original `user` of the request, retained locally; at most 256 characters.

{}

- finish_reason (required): s709

### s709: string | null

Why the answer of the first choice ended (`stop`, `length`, `tool_calls`,
`content_filter`, `error`), or null if it did not end.

{}

```json
"stop"
```

- first_byte_latency (optional): s710

### s710: number | null

Milliseconds from receiving the request until the provider's first byte (streams) or
complete answer (non-streaming), or null if no provider answered.

double

{}

```json
310
```

- gateway_overhead (required): s711

### s711: number | null

Milliseconds, with microsecond precision, the gateway itself spent on the request:
`timings.total` minus the time spent waiting for providers (`timings.upstream`,
`timings.streaming`) and for memory budgets or the record queue (`queue_time`).
It includes reading the request body (`timings.body`). Null if not measured.
Gateway extension.

double

{}

```json
0.412
```

- generation_time (required): s712

### s712: number | null

Milliseconds the serving provider took, from sending it the request until its answer
ended, or null if no provider answered.

double

{}

```json
1180
```

- http_referer (required): s713

### s713: string | null

HTTP-Referer application header, retained locally and bounded.

{}

- id (required): s714

### s714: string

ID of the generation, the same as the `id` of the chat completion and the
`x-generation-id` response header.

{}

```json
"gen-01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- is_byok (required): s715

### s715: boolean

Whether the last inference attempt used the organization's own provider credential.

{}

- latency (required): s716

### s716: number | null

Milliseconds from receiving the request until the generation ended.

double

{}

```json
1250
```

- media_conversions (optional): s717

### s717: integer

Completed media transport conversions across attempts. Omitted when none occurred;
includes URL loading for OCR and never contains media URLs, tokens or contents.

int32

{"minimum":"0"}

```json
1
```

- metadata (optional): s718

### s718: object

Caller metadata (at most 16 string pairs, keys 1..64 and values 0..512 characters).

{}

```json
{
  "workflow": "support"
}
```

- * (optional): s1166

### s1166: any

{}

- model (required): s719

### s719: string

The model that served the generation, after aliases and fallbacks.

{}

```json
"deepseek/deepseek-v4.1-flash"
```

- model_change (optional): s720

### s720: object

Unexpected response model. Only curated known model names are exposed.

{}

```json
{
  "actual_model": "curated-successor",
  "pricing_known": true
}
```

- actual_model (required): s881

### s881: string | null

Configured model identifier only; null for any unknown or oversized provider name.

{}

- pricing_known (required): s882

### s882: boolean

Whether a curated price list was available for this model.

{}

- moderation_latency (required): s721

### s721: number | null

Time spent in moderation. Always null: the gateway does not moderate.

double

{}

- native_finish_reason (required): s722

### s722: string | null

The provider's own finish reason of the first choice.

{}

```json
"stop"
```

- native_tokens_cached (required): s723

### s723: integer | null

Input tokens the provider read from its cache (0 if it reported none).

int64

{"minimum":"0"}

```json
0
```

- native_tokens_completion (required): s724

### s724: integer | null

Output tokens (including reasoning) as counted by the provider.

int64

{"minimum":"0"}

```json
25
```

- native_tokens_completion_images (required): s725

### s725: integer | null

Image tokens in the output. Always null: not tracked.

int64

{"minimum":"0"}

- native_tokens_prompt (required): s726

### s726: integer | null

Input tokens as counted by the provider.

int64

{"minimum":"0"}

```json
10
```

- native_tokens_reasoning (required): s727

### s727: integer | null

Reasoning tokens among the output tokens (0 if the provider reported none).

int64

{"minimum":"0"}

```json
5
```

- num_fetches (required): s728

### s728: integer | null

Web fetches. Always null: the gateway has no web fetch.

int64

{"minimum":"0"}

- num_input_audio_prompt (required): s729

### s729: integer | null

Audio inputs in the prompt. Always null: not counted.

int64

{"minimum":"0"}

- num_media_completion (required): s730

### s730: integer | null

Media items in the answer. Always null: not counted.

int64

{"minimum":"0"}

- num_media_prompt (required): s731

### s731: integer | null

Media items in the prompt. Always null: not counted.

int64

{"minimum":"0"}

- num_search_results (required): s732

### s732: integer | null

Web search results. Always null: providers report searches, not results.

int64

{"minimum":"0"}

- num_web_searches (required): s733

### s733: integer | null

Web searches charged for this generation (not part of OpenRouter's format); null if the
provider reported no usage. Their cost is part of `total_cost`, but not of
`upstream_inference_cost`.

int64

{"minimum":"0"}

```json
0
```

- ocr_cost (required): s734

### s734: number

Shared PDF extraction cost in EUR, included once in `total_cost`. Not included in any
`provider_responses[].usage.cost`, so provider expenses plus this field count OCR once.

double

{}

```json
0.002
```

- origin (required): s735

### s735: string

Origin of the request. Always empty: not recorded.

{}

```json
""
```

- original (required): s736

### s736: object | null

The cost of a generation in the provider's currency and the exchange rate that converted it
into EUR: `upstream_inference_cost` (EUR) is the input cost and the output cost, each
`cost × (1 + markup) / per_eur` rounded down to whole picos, added up.

{}

```json
{
  "currency": "USD",
  "exchange_rate": {
    "as_of": "2026-10-17T14:00:00Z",
    "markup": "0",
    "per_eur": "1.1645",
    "version": "ecb-2026-10-17"
  },
  "upstream_inference_cost": 0.0000244
}
```

- cost_details (optional): s1167

### s1167: oneOf

{}

oneOf: s1307

### s1307: object

Original-currency line items, without EUR-only OCR; absent in older receipts.

{}

```json
{
  "cache_read_cost": 0.000001,
  "cache_write_cost": 0,
  "completion_cost": 0.00002,
  "currency": "EUR",
  "media_cost": 0,
  "ocr_cost": 0,
  "prompt_cost": 0.00001,
  "reasoning_cost": 0,
  "request_cost": 0.001,
  "server_tool_cost": 0
}
```

- cache_read_cost (required): s572

Input tokens read from cache, including cached audio.

- cache_write_cost (required): s573

Input tokens written to cache, including extended TTLs.

- completion_cost (required): s574

Ordinary output tokens, excluding reasoning and audio.

- currency (required): s575

ISO 4217 currency for every line item; EUR for customer-facing costs.

- media_cost (required): s576

Input/output media tokens, image fees and transcribed seconds.

- ocr_cost (required): s577

Shared OCR preprocessing, charged once per generation and zero for provider expenses.

- pii_cost (optional): s578

Shared PII detection charge in EUR, included once in the customer total.

- prompt_cost (required): s579

Uncached ordinary input tokens.

- reasoning_cost (required): s580

Internal reasoning tokens.

- request_cost (required): s581

Fixed upstream request fee.

- server_tool_cost (required): s582

Native server tools, including web search.

oneOf: s588

### s588: null

{}

- currency (required): s1168

### s1168: string

Currency of the provider's price list (ISO 4217).

{}

```json
"USD"
```

- exchange_rate (required): s1169

### s1169: object

The exchange rate of the request.

{}

```json
{
  "as_of": "2026-10-17T14:00:00Z",
  "markup": "0",
  "per_eur": "1.1645",
  "version": "ecb-2026-10-17"
}
```

- as_of (required): s653

### s653: string

When the rates were published, RFC 3339 in UTC.

date-time

{}

```json
"2026-10-17T14:00:00Z"
```

- markup (required): s654

### s654: string

Markup for exchange-rate risk as a decimal fraction (`"0.02"` is 2 %).

{}

```json
"0"
```

- per_eur (required): s655

### s655: string

Units of the currency one euro buys (ECB convention), as a decimal string.

{}

```json
"1.1645"
```

- version (required): s656

### s656: string

Version of the rate snapshot.

{}

```json
"ecb-2026-10-17"
```

- upstream_inference_cost (required): s1170

### s1170: number

What the provider charged, in `currency`.

double

{}

```json
0.0000244
```

- parent_id (optional): s737

### s737: string | null

The earlier generation this one continues, when the gateway recognized the request as
the continuation of a conversation (agent chains); otherwise null.

{}

- pii_cost (optional): s578

Shared PII detection charge in EUR, included once in the customer total.

- preprocessing (optional): s738

### s738: array

Known paid OCR and PII attempts, including unusable paid responses before fallback,
plus one aggregate for free text decoding. At most 16 paid attempts of each kind.
No documents, plaintext, detector spans or responses.
Historical generations omit this extension rather than inventing quantities.

{"maxItems":"33"}

### s137: object

One evidenced preprocessing step, independent of later fallback or inference.

{"additionalProperties":"false"}

```json
{
  "cost_pico_eur": "2000000000",
  "exchange_rate": null,
  "id": "file-parser",
  "kind": "ocr",
  "model": "mistralai/mistral-ocr-4.1",
  "original_cost": {
    "currency": "EUR",
    "picos": "2000000000"
  },
  "price_version": "saved-tariff-hash",
  "provider": "mistral",
  "quantity": 2,
  "unit": "page"
}
```

- cost_pico_eur (required): s765

### s765: string

Customer charge in EUR picos, as an exact nonnegative integer string.

{"pattern":"\"^[0-9]+$\""}

```json
"2000000000"
```

- exchange_rate (required): s766

### s766: object | null

An exchange rate of the gateway's rate snapshot.

{}

```json
{
  "as_of": "2026-10-17T14:00:00Z",
  "markup": "0",
  "per_eur": "1.1645",
  "version": "ecb-2026-10-17"
}
```

- as_of (required): s653

When the rates were published, RFC 3339 in UTC.

- markup (required): s654

Markup for exchange-rate risk as a decimal fraction (`"0.02"` is 2 %).

- per_eur (required): s655

Units of the currency one euro buys (ECB convention), as a decimal string.

- version (required): s656

Version of the rate snapshot.

- execution (optional): s767

### s767: string

Execution mode; absent in native and historical receipts.

"native", "llm_span_extract", "llm_vision_transcribe"

{}

- fallbacks (optional): s768

### s768: array

On a `text_layer` receipt: one entry per document for which automatic file-parser
continued with paid OCR after the text layer, in document order. Absent otherwise.

{"maxItems":"16"}

```json
[
  "no_text"
]
```

### s214: string

Why automatic file-parser sent a document to OCR after the media worker's text layer.

"no_text", "worker_unavailable", "conversion_limit"

{}

- id (optional): s769

### s769: string

Executed bridge ID. OCR in Chat/Responses uses `file-parser`; absent for direct
preprocessing endpoints, PII detection and historical receipts.

{}

```json
"file-parser"
```

- kind (required): s770

### s770: string

`ocr`, `pii`, `transcription`, own `render`/`surcharge` lines, free gateway-only
`text` or the worker's PDF `text_layer`, never an inference token charge.

"ocr", "pii", "text", "render", "surcharge", "transcription", "text_layer"

{}

- model (required): s771

### s771: string

Public catalog model selected for this preprocessing attempt.

{}

```json
"mistralai/mistral-ocr-4.1"
```

- original_cost (required): s772

### s772: object

Exact contractual provider amount in the route tariff's native currency.

{"additionalProperties":"false"}

- currency (required): s936

### s936: string

Currency of the route tariff.

"EUR", "USD", "CHF", "GBP"

{}

- picos (required): s937

### s937: string

Nonnegative amount in 10^-12 currency units, as an exact integer string.

{"pattern":"\"^[0-9]+$\""}

```json
"2000000000"
```

- price_version (required): s773

### s773: string

SHA-256 of the immutable route price schedule, including its page/character tariff.
`free` for gateway-only text decoding, which has no tariff.

{}

```json
"b89318c1b25d981dd50b604ff1329a534e0e5459bfb409ac69ce61b5703f379c2"
```

- provider (required): s774

### s774: string

Configured provider identity, never credentials or a request URL.

{}

```json
"mistral"
```

- quantity (required): s775

### s775: integer

Exact billable pages or Unicode scalar values of this one attempt.

int64

{"minimum":"0"}

```json
2
```

- rejected_count (optional): s776

### s776: integer

Number of rejected span candidates, retained even if local parsing fails.

int64

{"minimum":"0"}

- task_version (optional): s777

### s777: string

Version of the gateway-owned LLM preprocessing task; never provider-authored text.

{"minLength":"1","maxLength":"64"}

- token_usage (optional): s778

### s778: object

Confirmed model tokens for LLM PII or image-chat OCR, never a substitute for the
scanned character or processed page quantity. Absent on page-priced native OCR.

{"additionalProperties":"false"}

- cache_write_tokens (optional): s941

### s941: integer

Input tokens written to cache, included in prompt_tokens; zero if unreported.

int64

{"minimum":"0"}

```json
0
```

- cached_tokens (optional): s942

### s942: integer

Input tokens read from cache, included in prompt_tokens; zero if unreported.

int64

{"minimum":"0"}

```json
0
```

- completion_tokens (required): s943

### s943: integer

All output tokens reported by the provider.

int64

{"minimum":"0"}

```json
128
```

- costs (optional): s944

### s944: object

Exact token pricing result. Required for LLM PII and OCR; optional for native OCR.

{"additionalProperties":"false"}

- customer (required): s938

### s938: object

Customer EUR costs, retaining the provider pricing path's group rounding.

{"additionalProperties":"false"}

- cache_read (required): s928

### s928: string

Cached input token cost.

{}

- cache_write (required): s929

### s929: string

Cache creation token cost.

{}

- completion (required): s930

### s930: string

Ordinary output token cost.

{}

- media (required): s931

### s931: string

Media cost.

{}

- prompt (required): s932

### s932: string

Ordinary input token cost.

{}

- reasoning (required): s933

### s933: string

Reasoning token cost.

{}

- request (required): s934

### s934: string

Fixed request cost.

{}

- server_tool (required): s935

### s935: string

Native server tool cost.

{}

- original (required): s939

### s939: object

Original-currency costs, before FX, in the enclosing original_cost currency.

{"additionalProperties":"false"}

- cache_read (required): s928

Cached input token cost.

- cache_write (required): s929

Cache creation token cost.

- completion (required): s930

Ordinary output token cost.

- media (required): s931

Media cost.

- prompt (required): s932

Ordinary input token cost.

- reasoning (required): s933

Reasoning token cost.

- request (required): s934

Fixed request cost.

- server_tool (required): s935

Native server tool cost.

- purchase (required): s940

### s940: object

Procurement EUR costs without customer markup, retaining exact group rounding.

{"additionalProperties":"false"}

- cache_read (required): s928

Cached input token cost.

- cache_write (required): s929

Cache creation token cost.

- completion (required): s930

Ordinary output token cost.

- media (required): s931

Media cost.

- prompt (required): s932

Ordinary input token cost.

- reasoning (required): s933

Reasoning token cost.

- request (required): s934

Fixed request cost.

- server_tool (required): s935

Native server tool cost.

- prompt_tokens (required): s945

### s945: integer

All input tokens reported by the provider.

int64

{"minimum":"0"}

```json
256
```

- reasoning_tokens (optional): s946

### s946: integer

Diagnostic reasoning counter, absent if unreliable or unavailable.

int64

{"minimum":"0"}

- unit (required): s779

### s779: string

`page` for OCR and the text layer; `character` for PII; `document` for free text
decoding; `second` for audio transcription.

"page", "character", "document", "second"

{}

- preset_id (required): s739

### s739: string | null

Preset of the request. Always null: there are no presets.

{}

- provider_name (required): s740

### s740: string | null

The provider that served the generation (the last one tried if every attempt failed),
or null if no provider was tried.

{}

```json
"scaleway"
```

- provider_responses (required): s741

### s741: array | null

All inference attempts, in order (at most 16), including failures and unknown usage.
Null when no attempt started. Known expenses and FX survive fallback independently
of content capture. No attempt is sent if its metadata cannot fit the attempt limit.

{"maxItems":"16"}

### s191: object

One provider attempt of a generation, in OpenRouter's shape.

{}

```json
{
  "id": "chatcmpl-abc123",
  "latency": 1200,
  "model_permaslug": "deepseek/deepseek-v4.1-flash",
  "provider_name": "scaleway",
  "status": 200
}
```

- error_type (required): s707

Error type in `error.metadata.type`, stable for programs. "Errors" in the introduction
lists the HTTP status and what to do for each.

- id (optional): s947

### s947: string

The provider's own response ID, omitted if absent, over 128 bytes, or containing
the credential used for that provider (including encoded forms).

{}

```json
"chatcmpl-abc123"
```

- is_byok (optional): s948

### s948: boolean

This attempt used the organization's own provider credential.

{}

```json
true
```

- latency (optional): s949

### s949: number

Milliseconds the attempt took.

double

{}

```json
1200
```

- model_permaslug (optional): s950

### s950: string

The model the attempt asked for.

{}

```json
"deepseek/deepseek-v4.1-flash"
```

- provider_name (optional): s951

### s951: string

The provider that was tried.

{}

```json
"scaleway"
```

- status (required): s952

### s952: integer | null

Original upstream HTTP status, null when not retained. The current normalizer
retains usage but not transport status; the gateway error is in `error_type`.

int32

{"minimum":"0"}

```json
200
```

- usage (required): s953

### s953: object | null

Provider usage retained per inference attempt, independently of the customer charge.
Amounts are exact pico-based EUR values. OCR is accounted for once on the generation.

{}

```json
{
  "cost": 0.000021,
  "currency": "EUR",
  "original": null,
  "server_tool_cost": 0,
  "tokens_cached": 0,
  "tokens_completion": 25,
  "tokens_prompt": 10,
  "tokens_reasoning": 5,
  "web_searches": 0
}
```

- cost (required): s1235

### s1235: number

Known expense for inference and server tools, excluding shared OCR. Retained even
when this attempt could not be served to the client. Never summed through floats.

double

{}

```json
0.000021
```

- cost_details (optional): s1236

### s1236: oneOf

{}

oneOf: s1332

### s1332: object

Disjoint provider expense line items; excludes shared OCR, absent in older receipts.

{}

```json
{
  "cache_read_cost": 0.000001,
  "cache_write_cost": 0,
  "completion_cost": 0.00002,
  "currency": "EUR",
  "media_cost": 0,
  "ocr_cost": 0,
  "prompt_cost": 0.00001,
  "reasoning_cost": 0,
  "request_cost": 0.001,
  "server_tool_cost": 0
}
```

- cache_read_cost (required): s572

Input tokens read from cache, including cached audio.

- cache_write_cost (required): s573

Input tokens written to cache, including extended TTLs.

- completion_cost (required): s574

Ordinary output tokens, excluding reasoning and audio.

- currency (required): s575

ISO 4217 currency for every line item; EUR for customer-facing costs.

- media_cost (required): s576

Input/output media tokens, image fees and transcribed seconds.

- ocr_cost (required): s577

Shared OCR preprocessing, charged once per generation and zero for provider expenses.

- pii_cost (optional): s578

Shared PII detection charge in EUR, included once in the customer total.

- prompt_cost (required): s579

Uncached ordinary input tokens.

- reasoning_cost (required): s580

Internal reasoning tokens.

- request_cost (required): s581

Fixed upstream request fee.

- server_tool_cost (required): s582

Native server tools, including web search.

oneOf: s588

- currency (required): s1237

### s1237: string

Currency of this attempt's `cost` and `server_tool_cost`, always EUR.

{}

```json
"EUR"
```

- original (required): s1238

### s1238: object | null

The cost of a generation in the provider's currency and the exchange rate that converted it
into EUR: `upstream_inference_cost` (EUR) is the input cost and the output cost, each
`cost × (1 + markup) / per_eur` rounded down to whole picos, added up.

{}

```json
{
  "currency": "USD",
  "exchange_rate": {
    "as_of": "2026-10-17T14:00:00Z",
    "markup": "0",
    "per_eur": "1.1645",
    "version": "ecb-2026-10-17"
  },
  "upstream_inference_cost": 0.0000244
}
```

- cost_details (optional): s1333

### s1333: oneOf

{}

oneOf: s1348

### s1348: object

Original-currency line items, without EUR-only OCR; absent in older receipts.

{}

```json
{
  "cache_read_cost": 0.000001,
  "cache_write_cost": 0,
  "completion_cost": 0.00002,
  "currency": "EUR",
  "media_cost": 0,
  "ocr_cost": 0,
  "prompt_cost": 0.00001,
  "reasoning_cost": 0,
  "request_cost": 0.001,
  "server_tool_cost": 0
}
```

- cache_read_cost (required): s572

Input tokens read from cache, including cached audio.

- cache_write_cost (required): s573

Input tokens written to cache, including extended TTLs.

- completion_cost (required): s574

Ordinary output tokens, excluding reasoning and audio.

- currency (required): s575

ISO 4217 currency for every line item; EUR for customer-facing costs.

- media_cost (required): s576

Input/output media tokens, image fees and transcribed seconds.

- ocr_cost (required): s577

Shared OCR preprocessing, charged once per generation and zero for provider expenses.

- pii_cost (optional): s578

Shared PII detection charge in EUR, included once in the customer total.

- prompt_cost (required): s579

Uncached ordinary input tokens.

- reasoning_cost (required): s580

Internal reasoning tokens.

- request_cost (required): s581

Fixed upstream request fee.

- server_tool_cost (required): s582

Native server tools, including web search.

oneOf: s588

- currency (required): s1168

Currency of the provider's price list (ISO 4217).

- exchange_rate (required): s1334

### s1334: object

The exchange rate of the request.

{}

```json
{
  "as_of": "2026-10-17T14:00:00Z",
  "markup": "0",
  "per_eur": "1.1645",
  "version": "ecb-2026-10-17"
}
```

- as_of (required): s653

When the rates were published, RFC 3339 in UTC.

- markup (required): s654

Markup for exchange-rate risk as a decimal fraction (`"0.02"` is 2 %).

- per_eur (required): s655

Units of the currency one euro buys (ECB convention), as a decimal string.

- version (required): s656

Version of the rate snapshot.

- upstream_inference_cost (required): s1170

What the provider charged, in `currency`.

- server_tool_cost (required): s1239

### s1239: number

Part of `cost` charged for server tools such as native web search.

double

{}

```json
0
```

- tokens_cache_written (optional): s1240

### s1240: integer

Input tokens written to cache, absent in receipts created before detailed pricing.

int64

{"minimum":"0"}

```json
0
```

- tokens_cached (required): s1241

### s1241: integer

Cached input tokens.

int64

{"minimum":"0"}

```json
0
```

- tokens_completion (required): s1242

### s1242: integer

Provider output tokens, including reasoning.

int64

{"minimum":"0"}

```json
25
```

- tokens_prompt (required): s1243

### s1243: integer

Provider input tokens.

int64

{"minimum":"0"}

```json
10
```

- tokens_reasoning (optional): s1244

### s1244: integer | null

Reasoning tokens among output tokens; `null` where the provider's counter is
unreliable and therefore not reported.

int64

{"minimum":"0"}

```json
5
```

- web_searches (required): s1245

### s1245: integer

Charged native web searches.

int64

{"minimum":"0"}

```json
0
```

- variant (optional): s954

### s954: string

Tariff variant of the attempted route, omitted for the standard route.

{}

```json
"cache"
```

- queue_time (required): s742

### s742: number | null

Milliseconds, with microsecond precision, the request waited for the gateway's memory
budgets (request bodies, provider responses) or for a place in the record queue; the
same as `timings.queue`. Null if not measured. Gateway extension.

double

{}

```json
0
```

- reasoning_effort (optional): s743

### s743: string

Reasoning effort the serving route applied: the requested or default effort mapped
to the nearest one the route offers, `none` when reasoning was switched off. Omitted
when the provider's own default applied or the model does not reason.

{}

```json
"low"
```

- request_id (required): s744

### s744: string | null

ID of the request, the same as its `x-request-id` header.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- request_parameters (optional): s745

### s745: object

Bounded validated request controls, without prompts, tool names/definitions, schemas
or stop sequences. `stop` and `tools` contain counts; `tool_choice` is a mode.
Unknown parameters appear only as bounded names in `unknown`. Missing controls stay
absent. `truncated: true` signals omitted metadata or exhausted process capacity.
`replay_complete: true` certifies that validated Chat controls are losslessly
represented here or in the separate content/attribution fields. Replay still requires
complete authorized content and attribution. Missing/false never permits replay;
nested controls omitted from this projection also make the certificate false.
Controls use validated Chat-compatible names after Responses translation; `api_type`
identifies the original endpoint. They describe requested values, not route defaults
or effective provider settings. Historical generations omit this extension.

{}

- requested_model (required): s746

### s746: string

The model the request named in `model`, as named: an alias stays an alias. Differs
from `model` when an alias or a fallback from `models` served the request.

{}

```json
"eu/fast"
```

- router (required): s747

### s747: string | null

The alias the request named if an alias led to `model` (for example `eu/fast`),
otherwise null.

{}

```json
"eu/fast"
```

- routing_decisions (optional): s748

### s748: array

Health decisions before attempts, at most 20 entries; never contains request content.

{"maxItems":"20"}

```json
[]
```

### s199: object

A bounded explanation of a skipped, deferred or forced route (gateway extension).

{}

- model (required): s974

### s974: string

Public model ID.

{}

```json
"mistralai/mistral-nemo"
```

- provider_name (required): s975

### s975: string

Configured provider ID, or endpoint tag `<provider>/<variant>` for a tariff variant.

{}

```json
"scaleway"
```

- reason (required): s976

### s976: string

Content-free explanation of the circuit or recovery decision.

{}

```json
"circuit open: cooldown"
```

- retry_after_ms (optional): s977

### s977: integer | null

Remaining cooldown at selection, in milliseconds; null when not applicable.

int64

{"minimum":"0"}

```json
30000
```

- traffic_percentage (required): s978

### s978: integer

Current allowed share of primary traffic.

int32

{"minimum":"0"}

```json
25
```

- service_tier (required): s749

### s749: string | null

Service tier the provider reported. Always null: not tracked.

{}

- session_id (optional): s750

### s750: string | null

Session the generation belongs to, or null.

{}

- streamed (required): s751

### s751: boolean | null

Whether the answer was streamed.

{}

```json
true
```

- timings (required): s752

### s752: object | null

Time of one request per phase, in milliseconds with microsecond precision, measured on a
monotonic clock from the request's arrival until the generation ended. Every moment
belongs to exactly one phase; each phase is rounded down to whole microseconds, so the
phases add up to `total` minus at most 0.008 ms. The gateway overhead is the sum of
`auth`, `body`, `validate`, `routing` and `post`.

{}

```json
{
  "auth": 0.081,
  "body": 0.034,
  "post": 0.079,
  "queue": 0,
  "routing": 0.096,
  "streaming": 940.374,
  "total": 1250,
  "upstream": 309.214,
  "validate": 0.122
}
```

- auth (required): s1171

### s1171: number

Accepting the request: authentication and customer admission.

double

{}

```json
0.081
```

- body (required): s1172

### s1172: number

Reading the request body from the client.

double

{}

```json
0.034
```

- post (required): s1173

### s1173: number

After a non-streaming answer: normalization, plugins, cost accounting and recording.

double

{}

```json
0.079
```

- queue (required): s1174

### s1174: number

Waiting for memory budgets (request bodies, provider responses) or for a place in the
record queue.

double

{}

```json
0
```

- routing (required): s1175

### s1175: number

Route selection, reservations and the gateway's work around each provider attempt.

double

{}

```json
0.096
```

- streaming (required): s1176

### s1176: number

Streams only: from the provider's first byte until the stream ended. Zero otherwise.

double

{}

```json
940.374
```

- total (required): s1177

### s1177: number

From the request's arrival until the generation ended (`latency` with microsecond
precision).

double

{}

```json
1250
```

- upstream (required): s1178

### s1178: number

Waiting for providers, all attempts together: from sending each attempt until its
first byte (streams) or complete answer (non-streaming), backoff between attempts, and
PDF extraction or PII detection before inference.

double

{}

```json
309.214
```

- validate (required): s1179

### s1179: number

Validating the request and checking it against the key's policy.

double

{}

```json
0.122
```

- tokens_completion (required): s753

### s753: integer | null

Output tokens as counted by the provider, or null if it reported none.

int64

{"minimum":"0"}

```json
25
```

- tokens_prompt (required): s754

### s754: integer | null

Input tokens as counted by the provider, or null if it reported none.

int64

{"minimum":"0"}

```json
10
```

- total_cost (required): s755

### s755: number

Customer-facing cost in EUR: the last attempt's known usage plus OCR once (also on
failure). Earlier failed attempts are platform expenses, recorded separately in
`provider_responses[].usage`; they are not added to this charge. Without last-attempt
usage, only OCR is known here. Zero does not mean earlier attempts were free.

double

{}

```json
0.000021
```

- trace (optional): s756

### s756: object

Explicit trace association and custom trace properties, retained locally.
At most 21 entries; keys 1..64 characters, names at most 512 characters, IDs never shortened,
custom values at most 512 JSON bytes. X-Trace-Id supplies a missing trace_id.

{}

```json
{
  "trace_id": "example-trace"
}
```

- * (optional): s1180

### s1180: any

{}

- upstream_id (required): s757

### s757: string | null

The provider's own ID of its response, or null if absent, longer than 128 bytes,
or containing the credential used for that provider (including encoded forms).

{}

```json
"chatcmpl-791bcf62-080e-4568-87d0-94c72e3b4946"
```

- upstream_inference_cost (required): s758

### s758: number | null

Input and output inference expense in EUR, including media but excluding request,
server-tool and OCR fees; null without complete provider usage.

double

{}

```json
0.000021
```

- usage (required): s759

### s759: number

Cost in EUR, the same as `total_cost`.

double

{}

```json
0.000021
```

- usage_estimate (optional): s760

### s760: object

UTF-8 text estimate when provider usage is missing. Diagnostic only, except for a
cancelled generation whose provider usage could not be read: then its tokens and cost
are this estimate at the route's normal prices, within the request's reservation.

{}

```json
{
  "completion_tokens": 2,
  "estimated": true,
  "method": "utf8_bytes_div4",
  "prompt_tokens": 4
}
```

- completion_tokens (required): s1039

### s1039: integer

Rounded-up emitted text, reasoning and tool-argument bytes divided by four.

int64

{"minimum":"0"}

- estimated (required): s1040

### s1040: boolean

Always true.

{}

- method (required): s1041

### s1041: string

Fixed estimator identifier, never provider-authored text: `utf8_bytes_div4` for a
diagnostic estimate, `delivered_utf8_bytes_div4` for a billed cancellation estimate.

{}

- prompt_tokens (required): s1042

### s1042: integer

Rounded-up UTF-8 text bytes divided by four; excludes image/audio payloads.

int64

{"minimum":"0"}

- total_tokens (required): s1043

### s1043: integer

Sum of the two estimated text-token counts.

int64

{"minimum":"0"}

- user_agent (required): s761

### s761: string | null

User-Agent header of the request, retained locally and bounded.

{}

- variant (optional): s762

### s762: string

Tariff variant of the provider's route that served the generation (endpoint tag
`<provider_name>/<variant>`, e.g. `grunden/cache`), requested with `provider.only` or
`provider.order`; omitted for the standard route.

{}

```json
"cache"
```

- web_search_engine (required): s763

### s763: string | null

`native` if the provider searched the web for this generation (the gateway offers only
the provider's own search), otherwise null.

{}

- workspace_id (required): s764

### s764: string | null

Compatibility attribution: the organization's ID. This field does not identify a
management workspace; use the management API for the key's actual workspace.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

- session_id (required): s987

### s987: string

The session ID, as sent in `x-session-id` or `session_id`.

{}

```json
"support-chat-4711"
```

- total (required): s988

### s988: integer

How many generations of the session this gateway instance keeps. If it is larger than
the number of `generations`, only the most recent ones are listed.

int64

{"minimum":"0"}

```json
2
```

## Response 400: application/json

The session ID is too long, has other characters or consists only of dots (`invalid_parameter`)

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (required): s238

### s238: object

What went wrong.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Providers that serve the model (when `provider.only` excluded all of them).

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (required): s636

### s636: string

Kind of problem, stable for programs.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

```json
"temperature must be at most 2, got 5"
```

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

```json
"provider.only"
```

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Response 401: application/json

Missing, invalid or expired API key (`authentication`)

## Response 404: application/json

No generation of this session for the key's organization and workspace: unknown, sent by another organization or workspace, not yet ended, or no longer kept (`not_found`)

## Response 429: application/json

Customer quota exhausted (`rate_limited`); retry after Retry-After

## Response 500: application/json

Unexpected gateway error (`internal`)

## Response 503: application/json

Shared customer admission unavailable; retry shortly (`no_provider_available`)
