FeaturesRouting policies

Using routing policies

How Gateway resolves which policy applies to a request, and how to control it from the request payload.

A routing policy isn’t sent in the request body. Gateway resolves it for you on every call based on what you attach to the request and what’s configured on your org. This page covers how that resolution works and what you can do from the request side.

How routing policies are applied

Routing policies are attached to projects or set as the org default. When Gateway receives a request, it resolves the policy in this order:

  1. Project-scoped policy - if the request includes a project (via the project_id body field) and that project has a routing policy, Gateway uses it.
  2. Org default policy - if no project is specified, or the project has no routing policy, Gateway falls back to the org-level default policy.
  3. No policy - direct model calls - if neither exists, Gateway routes directly to the model specified in the request.

When a routing policy is active, the model field in your request is optional - the policy selects the provider and model automatically. Omit it for Priority and Intelligent routing. model is only required when no policy resolves for the request.

Switching strategies per request

You cannot pass a routing strategy in the request body. To route different requests through different strategies:

  1. Create one project per strategy - e.g., one with Cost Optimized, another with Quality First.
  2. Pass the appropriate project_id field in the request body per request. All projects share the same API key.

This is useful when different features or user tiers need different cost/quality trade-offs.

Using default_routing

Set the request’s model field to the sentinel value "default_routing" to explicitly request policy-based routing without naming a model.

model valueBehavior
Omitted or nullHand off to the configured routing policy.
"default_routing"Same as omitted - hand off to the configured routing policy.
"provider/model" (e.g. "openai/gpt-5.2")Bypass policy selection and route directly to that model.
"model-name" bare (e.g. "gpt-5.2")Server-side resolution to a fully-qualified ID; rejected if ambiguous.

The sentinel value is case-insensitive and whitespace is stripped, so " Default_Routing " resolves the same as "default_routing".

default_routing is useful when you have a client that always sends a model field - for example, the OpenAI SDK or a templated request payload - but you want every request to honor the project or org default policy. Set the value once at the client level and Gateway will pick the model.

1from merge_gateway import MergeGateway
2
3client = MergeGateway(api_key="YOUR_API_KEY")
4
5response = client.responses.create(
6    model="default_routing",
7    input=[
8        {"type": "message", "role": "user", "content": "Draft a response to this support ticket."},
9    ],
10    project_id="production",
11)
12
13print(response.output[0].content[0].text)

If no routing policy resolves for the request (no project policy and no org default), Gateway rejects requests sent with model: "default_routing" because there’s no policy to hand off to. Either configure an org default policy or send a concrete model ID.

FAQs

No. Routing strategies live on policies, which are attached to projects or set as the org default. There is no type, axis, or strategy field on the POST /responses request body. To switch strategies per request, use different projects with different policies and pass the matching project_id field in the request body.

Only when no routing policy applies. If a policy is active (via project or org default), omit model or pass "default_routing" - the policy picks the provider and model for you. This works for Priority and Intelligent routing.

Create one project per strategy and switch via the project_id field in the request body. All projects share the same API key, so you don’t need multiple keys. Omit the field to hit the org default.

Gateway returns an error after all failover attempts are exhausted. Provider health is tracked automatically so requests skip providers that are currently down.

No. One org-level default. You can have one additional policy per project for project-scoped routing.