Skip to content
IQ Routing

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 -- classifies the prompt and routes across the full range, from your cheapest tier up to your flagship.
  • frontier -- routes across a premium-only ladder; even its cheapest rung is a full current-generation model, never a lightweight or legacy one.
  • cheap -- routes across a cost-capped ladder that never reaches your top-tier flagship.
  • auto-coding -- task-intent alias for coding workloads; resolves through the frontier ladder today.
  • auto-research -- task-intent alias for research workloads; resolves through the frontier ladder today.
  • default -- resolves to one model the gateway has chosen as a stable starting point; behaves like a concrete id from there, including the family lock described below.

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 paid plans 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. Free 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.

One model sits outside this whole system. claude-fable-5 is never a rung in any alias's ladder and is never reached by the family lock's fallback climb described above; the only way to reach it is the cap:orchestrate capability handle, named explicitly per request. See capability aliases for what that handle does and the limits that come with it.