Request fields

Route selectors

Every request sends exactly one of these. Sending both, or neither, returns 400.

See Choose a model for the ID syntax and Add fallbacks for how Router walks the list.

OpenAI fields

Router passes the standard Responses create payload through, including input, instructions, tools, text, reasoning, metadata, max_output_tokens, and stream. Which ones work depends on the selected model's capabilities — a request for a capability the provider cannot satisfy returns 501.

metadata is stored with the usage record and shown in request details. See Track spend by feature.

Router-only fields

Frameworks reach these through extra_body or an equivalent escape hatch. See Connect your app.

Timeouts

provider_timeout and timeout_before_headers are positive numbers of seconds. Each gateway sets a maximum; a value above it is rejected with 400 invalid_request naming the field and the maximum, rather than being silently clamped. Read the maximum off that error rather than assuming a number.

For a buffered request, provider_timeout applies to each candidate separately, so a fallback list can take up to the timeout multiplied by the number of candidates. Set your client deadline accordingly.

For a streaming request, timeout_before_headers bounds startup — the window in which Router can still fall back to another model — and provider_timeout bounds idle time between events after the stream commits.

allow_flex_tier

When omitted, eligible requests follow your account's cost-efficient routing setting. An explicit true or false always wins over that setting.

Only eligible models have Flex capacity. Asking for it where it does not exist — allow_flex_tier: true on another model — returns 400 rather than being ignored, so set the opt-in on the call sites that use a Flex-capable model rather than globally on a shared client. An explicit false is always accepted and is safe to send from a shared client:

{
  "error": {
    "message": "`allow_flex_tier` is only supported for eligible directly registered models.",
    "code": "invalid_request"
  }
}

Adaptive Flex applies only to a direct model, so it never affects models lists.