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, medium, 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 your chosen flagship, configurable per team. A preferred-model list overrides the default when you set one, and an allowed-model list bounds the search so a runaway prompt cannot escalate to the most expensive tier.

Routing aliases

auto is one of six routing aliases you can pass as model:

auto-coding and auto-research are task-intent aliases: they name the kind of work instead of a cost/quality band directly, and the gateway currently maps both onto the frontier ladder. Use them when you want the call site to say what the request is rather than which band to route it through; use frontier directly when you want to name the band.

Customising the ladder behind an alias

On Team and Enterprise you can customise the model ladder behind auto, cheap, and frontier, choosing which models sit in which complexity band. Because auto-coding and auto-research resolve through the frontier ladder, a custom frontier ladder governs them too. That is how you keep auto pointed at the models you actually trust for hard work while holding cheap traffic on whatever you have decided is good enough, without changing a line of client code. Basic stays on the stock ladder.

Fallback loop

If the chosen provider returns a retryable error (429, 500, 503, network timeout), the gateway falls back to the next model in that tier’s chain, with a cheap model appended as last-resort insurance. The chain is ordered and finite, each rung carries a per-call timeout, and the whole fallback loop runs under a hard wall-clock ceiling, so a provider that accepts a connection and then goes quiet cannot hold your request open indefinitely. The requests browser records the provider that actually served each request, whether a fallback was used, and the per-rung attempt trail, so a degrade reads as “asked for X, served Y” rather than a bare flag.

Sending a concrete model id

Pass an explicit model id (claude-opus-5, claude-opus-4-8, claude-haiku-4-5, gpt-5-mini) instead of auto when your client is bound to one provider’s conventions. A concrete id is read as a family lock rather than as a pin: the classifier still scores the prompt and picks the tier, but every candidate and every fallback rung is drawn from that provider’s own ladder, so a coding harness built around one vendor’s system prompt and tool protocol never lands on a foreign model mid-loop. A hard turn climbs that family’s ladder and a cheap turn drops down it.

That means the model you name is a family and a starting point, not a guarantee of the exact id. For deliberate steering, use one of the routing aliases above instead of a concrete id. auto, cheap, frontier, auto-coding, and auto-research route across providers and are unaffected by the family lock. default is the exception: it resolves to one fixed model the gateway chooses, which then triggers this same family lock as if you had named that model directly — unless your org holds no key for that provider, in which case the request falls open to auto-style routing instead.