Routing

When a request arrives with model="auto", the gateway classifies the prompt and emits two labels: a complexity tier (simple, medium, complex) and a thinking budget tier (none, low, high). Both labels ride on the request row and on the x-iq-routing telemetry header so you can see what the gateway decided for any request.

Picking the provider

The complexity tier maps to a model tier: simpler prompts route to cheaper, faster models and harder prompts route to the operator's chosen flagship (configurable per team). The team's preferred_models list overrides the default when set, and the allowed_models list bounds the search so a runaway prompt cannot escalate to the most expensive tier.

Fallback loop

If the chosen provider returns a retryable error (429, 500, 503, network timeout), the gateway falls back to the next provider in the same tier. The fallback chain is bounded so an outage never burns more than three upstream calls per request. The chosen_provider and fallback_used columns in the requests browser record what actually shipped.

Pinning a model

Pass an explicit model id (claude-haiku-4-5, gpt-4o-mini, gemini-2.5-flash) instead of auto when you need a deterministic choice. The classifier still runs to compute the thinking budget, but the provider and model are taken from the request unchanged.