Routing
A routing policy decides which model and vendor handles each employee request. Instead of every employee naming a model in their own client config, they send default_routing and the policy chooses, which means you can change the model a team uses without touching a single laptop.
Policies live on the Routing policies tab, one row each with its name, type, axis, and what it is used by. A policy either governs your whole organization as the default, or is scoped to one Group.
Strategies
Client errors (400 to 404) never trigger failover on a Priority policy; vendor throttles and outages do. Vendor health is tracked automatically, so a vendor accumulating failures is skipped rather than retried into.
Intelligent routing embeds each prompt, scores its complexity from 0 to 1, and maps the score to a model tier inferred from output token price. It adds 1 to 4 ms, negligible against inference time, and the router only ever selects from the models in your policy. If the scorer fails, the request goes to the most capable model in the policy rather than the cheapest.
Gateway supports two more strategy families: latency- and cost-ranked routing, and Build Your Own Router, which scores models against benchmarks you pick. Both are configured in the Gateway console. A policy using one appears in the Routing policies tab with Editable in Merge Gateway only in place of Edit, because saving from here would send a strategy the write path refuses. Set as default is withheld for the same reason. Delete still works.
Attaching a policy
Every request resolves a policy in the same order:
- The policy scoped to the employee’s Group
- The organization default
- No policy, in which case the model named in the request is used directly
That resolution is the whole of the model. Scope a policy to a Group when one team needs different cost or quality trade-offs from the rest, and leave everyone else on the default.
The Used by column says what a policy actually governs: All employees for the default, the Group name for a scoped policy, and Not used by any group for a policy that is stored and reaching nobody. That last state is the one worth checking after an edit.
To change the default, open a policy’s row menu and choose Set as default. Gateway demotes whichever policy held it. An Inactive badge means the policy is switched off in Gateway and will not be selected at routing time, which is a different thing from not being the default.
A developer calling Gateway directly can name a policy per request instead, which is covered in Using policies; for a fleet of employee clients, the Group and organization scopes are what you want.
Model aliases
Every policy also has a virtual model name, @alias/<slug>, minted from the policy’s name: “Fast experiment” becomes @alias/fast-experiment, and the organization default becomes @alias/default. Send it where a model name goes and the request routes through that policy.
This is the alternative to default_routing when you want employees on different policies without issuing them different keys. The alias is the stable name in the employee’s config; the policy behind it is yours to change whenever.
Gateway advertises your aliases in its model listing, so they show up in a client’s model picker alongside the catalog.
Four rules worth knowing before you put an alias in a fleet config:
- Renaming a policy never changes its alias. The alias is embedded in configuration you have already shipped, so a rename must not break it. Change an alias explicitly when you want a new one, and expect anything still sending the old one to get
404s. - Aliases are unique. A second policy named “Fast experiment” gets
@alias/fast-experiment-2. - Deleting the policy deletes the alias, freeing the name for reuse
- Aliases resolve on the chat surfaces only. Embeddings, image, audio, and video endpoints reject an
@alias/model, since a routing decision has nothing to select from there.
Routing on tags
Tags are key-value pairs attached to requests, defined on the Advanced tab. Routing rules that read them are evaluated in priority order, the first match wins, and anything unmatched falls through to the strategy above. Configure the rules themselves in the Gateway console.
FAQs
Can an employee route around the policy?
They can name a specific model, which skips the routing decision but not your access checks, guardrails, or budgets. Blocklist rules and vendor restrictions are evaluated before routing, so a named model that your organization blocks is refused either way.
How many default policies can I have?
One for the organization, plus one policy per Group. Beyond those you can hold as many policies as you need, but a policy that is neither the default nor scoped to a Group reaches nobody.
Do I have to list every approved model in the policy?
No. The policy is the candidate set for the strategy, not your allow list. What employees may reach is set on Model access, and a model that your blocklist covers is filtered out of the candidate set before scoring.
Next
For the full strategy reference, including the tier thresholds and the vendor selection rules, see Routing policies.