> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing

> NagaAI picks a provider for every chat request and moves it to another on failure; a routing strategy sets the order.

## What NagaAI does with each request

Most models in the catalog are served by several providers. For every chat request NagaAI:

1. Takes the providers that serve the requested model and are healthy right now.
2. Orders them by the routing strategy.
3. Sends the request to the first one. If that provider fails with a timeout, a `5xx`, a rate limit or an exhausted quota, NagaAI tries the next one, up to three attempts. NagaAI does not retry a `400` or `422` from a provider.

You get one answer or one error. The response never names the provider, and NagaAI does not charge failed attempts. The `model` field of the response is the NagaAI catalog id, whichever provider answered.

Because the provider can change from one request to the next, two identical requests can land on different providers. Latency, cache hits and exact wording can differ between them.

## Strategies

A strategy changes the order in which NagaAI tries providers. It never removes a provider and never makes a request fail.

| Strategy      | Prefers                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `reliability` | The provider with the best recent success rate                                                           |
| `balanced`    | Speed, among providers whose success rate is close to the best                                           |
| `latency`     | The shortest time to the first token. Without streaming, the fastest complete answer                     |
| `throughput`  | The most output tokens per second                                                                        |
| `cache`       | Providers that return prompt-cache reads for this model, which lowers the price of long repeated prompts |

If you do not choose a strategy, NagaAI chooses one, and the response header below tells you which.

Strategies apply to `/v1/chat/completions`, `/v1/responses` and `/v1/messages`. Images, audio, embeddings and moderation ignore them.

## Choosing a strategy

There are three places to set one. When more than one is present, the first in this list wins.

1. The request body: a top-level `routing` object.
2. The `x-naga-routing-strategy` request header.
3. The API key's default, set through the [API keys API](/account/api-keys).

### In the request body

```json theme={null}
{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "Hello"}],
  "routing": {"strategy": "latency"}
}
```

The same `routing` object works in all three chat formats. The value is case-sensitive. An unknown strategy or an unknown key inside `routing` fails with `400 invalid_request_error`:

```json theme={null}
{"error": {"type": "invalid_request_error", "message": "body.routing.strategy: unknown variant `fast`, expected one of `reliability`, `balanced`, `latency`, `throughput`, `cache` at line 1 column 114"}}
```

SDKs pass extra body fields through their own option:

<CodeGroup>
  ```python Python theme={null}
  completion = client.chat.completions.create(
      model="claude-sonnet-5",
      messages=[{"role": "user", "content": "Hello"}],
      extra_body={"routing": {"strategy": "latency"}},
  )
  ```

  ```javascript Node.js theme={null}
  const completion = await client.chat.completions.create({
    model: "claude-sonnet-5",
    messages: [{ role: "user", content: "Hello" }],
    routing: { strategy: "latency" },
  });
  ```
</CodeGroup>

### In a header

Use the header when you cannot change the body, for example in a tool that only lets you add headers.

```http theme={null}
x-naga-routing-strategy: throughput
```

The header is case-insensitive. NagaAI ignores an unknown value in the header instead of failing the request.

### As a key default

Set `default_routing_strategy` when you create or update a key through the account API. Every request made with that key uses the strategy unless the body or the header names another. Send `null` in an update to go back to letting NagaAI choose.

```bash theme={null}
curl -X PATCH https://api.naga.ac/v1/account/keys/KEY_ID \
  -H "Authorization: Bearer $NAGAAI_PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_routing_strategy": "cache"}'
```

## Checking which strategy ran

Every successful chat response carries the strategy NagaAI used:

```http theme={null}
x-naga-routing-strategy: latency
```

Errors returned before NagaAI reaches a provider do not carry this header.

## What you cannot choose

NagaAI does not let a request name a provider, exclude one, or list fallback models. To use another model after a failure, catch the error and send a new request with that model.