Routing policies
A routing policy picks the model and vendor for each request, so your code doesn’t hard-code a model. Use one for cross-vendor failover, a cost or quality target, or model changes without a deploy.
Select a policy with a model alias
Every organization-level policy gets a model alias from its name. Send the alias as model to route through that policy. This is the recommended approach: one API key reaches every policy, and policy edits reach every caller without a code change.
Set model to the policy’s alias, such as @alias/support-agent.
Policies can also apply through a key binding, a project or customer default, or the organization default. See Model aliases and policy precedence.
Strategies
Create policies under Routing policies → Policies and set the organization default under Configure → Request settings → Defaults.
The /v1/routing-policies API creates Priority and Intelligent policies. Pick Priority for predictable, ordered failover, Intelligent to send easy prompts to cheaper models, and Build Your Own Router when you have evaluation data.
A policy chooses only among the models you add. The picker lists catalog models your organization’s vendor, region, zero data retention, and credential settings allow. Intelligent also needs catalog capability metadata, so a model can appear for Priority but not Intelligent.
Reasoning effort
Priority and Intelligent policies can set a default reasoning.effort for requests that omit it, plus minimum and maximum limits (Build Your Own Router can’t). Per-model overrides set to Inherit use the policy value. Levels run none, minimal, low, medium, high, xhigh, max, and each model accepts only the levels it supports.
How Gateway picks a vendor
Vendor selection works the same whether a policy chose the model or you named it. Gateway starts from every active route for the model and drops routes that fail zero data retention, your organization’s vendor and region restrictions, or the request’s required capabilities (such as tools or structured output). Routes that honor the requested reasoning.effort are preferred, not required. A vendor or vendors pin then picks from the survivors, so a pin can’t bypass organization restrictions. Without a pin, your organization’s vendor routing preference applies; otherwise the cheapest route wins on combined input and output price per million tokens at the current rate, with catalog priority breaking ties.
The model’s direct provider, meaning the company that created it, gets no routing preference. For example, deepseek/deepseek-v4-pro can be served by another eligible vendor when that route is cheaper. Failover candidates follow the same order, with the cheapest capable route first. Pin a vendor when the route matters; the x-merge-vendor header (or routing.vendor_used with routing metadata on) shows which vendor served you.
Tag-based routing
Tag rules send a request to a different strategy within a project policy. Send key-value pairs in the request’s tags body field. A rule matches when every pair it lists appears on the request with the same value; extra request tags don’t prevent a match. The first matching rule in list order wins. If no rule matches, the policy’s default strategy applies. Configure rules on a project’s Routing tab in Projects. Customer policies don’t support tag rules.