---
title: "Provider routing"
subtitle: "Control which providers and keys serve a request, and in what order."
---

For every request, the gateway turns the model you asked for into an ordered list of attempts. Each attempt is one provider's offering of a model on one key. The gateway sends the first attempt and moves to the next only if it fails, so the first attempt that answers is the one you get. The defaults work without any setup: a model name such as `gpt-5.5` already lists every provider that serves it, and your own provider keys serve first.

```bash
curl https://gateway.respan.ai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "azure/gpt-5.5", "messages": [{"role": "user", "content": "Hello!"}]}'
```

## Routing controls

| Control | Type | Default | Description |
|---|---|---|---|
| [`model`](#model) | string | required | A model name, provider offering, or [route](/docs/ai-gateway/routing/routes-and-aliases). |
| [`X-Respan-Route-Provider`](#pin-a-provider) | header | none | Pins a Messages, Responses, or Gemini request to one provider without changing the model ID. |
| [`x-respan-managed-fallback-enabled`](/docs/ai-gateway/routing/fallbacks#managed-fallback) | header | off | Lets Respan's keys serve after your own key answers `429`. |
| [`x-respan-beta: env-scoped-integrations-2026-03-28`](#environment-scoped-keys) | header | off | Uses only the provider keys of your API key's environment. |
| [Key weight](#key-weights) | deployment setting | `1` | Splits traffic across your own keys for one provider. |
| [Routes](/docs/ai-gateway/routing/routes-and-aliases) | `/api/routes/` | none | Your project's named fallback chains and weighted splits. |

Each provider call has a fixed upstream timeout of 600 seconds.

## How attempts are built

1. **Resolve the name.** If your project has a route with that name, its entries are used, in order or by weight. Otherwise a Respan alias of that name is used. Otherwise the name is a model: every provider offering of it in the catalog, in [provider order](#provider-order). A provider offering such as `azure/gpt-5.5`, a `<provider>/` prefix, or a [pin](#pin-a-provider) keeps only that provider.
2. **Pick keys for each offering.** Keys are tried pool by pool: your project's own keys ([BYOK](/docs/ai-gateway/spend/credits-vs-byok#byok)), keys your workspace shares, Respan keys dedicated to your organization, then Respan's public keys. Within a pool, your keys for one provider are split by [weight](#key-weights).
3. **Keep your keys separate from Respan's.** If any of your own keys can serve the model, Respan's keys are left out, unless the request opts in to [managed fallback](/docs/ai-gateway/routing/fallbacks#managed-fallback); then they serve only after your key answers `429`. Respan's keys only serve offerings credits can pay for.
4. **Drop what can't be sent.** An attempt whose provider doesn't serve this kind of request (chat, images, embeddings, and so on) is skipped.
5. **Send in order.** The gateway sends each attempt until one answers. See [Fallbacks](/docs/ai-gateway/routing/fallbacks#how-failover-works).

## model

`model` is where routing starts. Each form resolves differently:

| You send | Attempts |
|---|---|
| `gpt-5.5` | Every provider of the model, in provider order, your own keys first. |
| `azure/gpt-5.5` or `openai/gpt-5.5` | That provider's offering only. |
| `smart` | Your route's entries. See [Routes and aliases](/docs/ai-gateway/routing/routes-and-aliases). |

## Pin a provider

To call one provider only, send its offering as the model ID, such as `azure/gpt-5.5`, or put the provider's prefix in front of the model name, such as `openai/gpt-5.5`. This works on every format, Chat Completions included. Copy the exact ID from the model's **Providers** tab in **Gateway** › **Models**.

When a client can't change the model ID, for example a CLI agent that always sends `claude-sonnet-4-5-20250929`, send the `X-Respan-Route-Provider` header instead. The header is read on Anthropic Messages (`/v1/messages`), OpenAI Responses (`/v1/responses`), and Gemini (`/v1beta/models/{model}:generateContent`). Its value is the provider's ID, such as `anthropic` on Messages, `google_gemini_ai` on Gemini, or `azure` on Responses.

```bash
curl https://gateway.respan.ai/v1/messages \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-Respan-Route-Provider: anthropic" \
  -d '{"model": "claude-sonnet-4-5-20250929", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello!"}]}'
```

A pinned request uses only that provider's offerings, on every key pool. If the provider doesn't serve the model, the request is refused with `model '<id>' is not available on provider '<provider>'`.

## Provider order

A model name's offerings are ordered from the catalog:

1. Your project's custom offerings of the model.
2. The model's default provider, usually its maker.
3. The rest, from cheapest catalog price.

Key pools come first, whatever the order: every offering your own keys can serve is tried before any offering on Respan's keys. Within your own keys, the model's maker is tried first, such as OpenAI for `gpt-5.5`, before a reseller. Respan's keys keep the catalog order.

## Key weights

Each provider key you add is a deployment. When more than one of your deployments can serve an offering, the gateway picks one per request by its **Load balance weight**. If the picked key fails, it picks again from the remaining keys by weight, so every key gets a turn before the request moves on.

Set weights under **Gateway** › **API keys** › **Bring your own key** › your provider. A key's **Available models** and **Exclude models** settings also filter which offerings it serves. See [Load balancing](/docs/ai-gateway/routing/load-balancing#balance-across-your-own-keys).

## Environment-scoped keys

Send `x-respan-beta: env-scoped-integrations-2026-03-28` to scope the request to the provider keys (integrations) of your API key's environment. A test API key then uses only test keys, besides Respan's.

## See which provider served a request

Every response carries two headers:

| Header | What it is |
|---|---|
| `X-Respan-Log-Id` | The ID of the request's log. |
| `X-Respan-Gateway-Request-Id` | The ID shared by every row the request writes. |

Open the log in **Gateway** › **Logs**:

- The log names the model, the provider, and the deployment that served the call. The **Config** tab's **Billing method** shows **BYOK** or **Respan credits**.
- Each request is one trace. When earlier attempts failed, each attempt is a row in that trace, so you can see every provider that was tried.

To list every request one key served, filter Logs by **Deployment**, or use the [request logs API](/docs/ai-gateway/observability/logs-and-traces).

## Related

- [Fallbacks](/docs/ai-gateway/routing/fallbacks)
- [Load balancing](/docs/ai-gateway/routing/load-balancing)
- [Routes and aliases](/docs/ai-gateway/routing/routes-and-aliases)
- [Models and providers](/docs/ai-gateway/models/overview)