> ## 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.

# The routing object

> The routing object sets which provider NagaAI tries first, the most a request pays per unit of each meter, and the precisions it accepts.

Use the routing object to make a request faster, more reliable, cheaper, or more exact than NagaAI's default choice. It's a NagaAI field, so the OpenAI and Anthropic APIs don't have it.

## Where it appears

You send the object as the top-level `routing` field of a request body:

* `strategy`, `max_price` and `precision`: `POST /v1/responses`, `POST /v1/chat/completions`, and `POST /v1/messages`.
* `max_price` and `precision`: the image, video, audio, embeddings, moderation, and rerank endpoints. In a form, the OpenAI SDKs send `precision` as repeated `routing[precision][]` parts.

The object is optional. If you omit it, NagaAI orders the providers by price and its own strategy, with no price limit, and in any precision.

## Attributes

**strategy** `enum\<string\>`

The order in which NagaAI tries providers at the same price. Chat endpoints only; see [Strategy values](#strategy-values).

If omitted, NagaAI uses the `x-naga-routing-strategy` header, then the key's default, then the workspace's, then its own choice.

**max\_price** `object`

The most one unit of each named meter may cost, in credits. Only providers at or below every cap serve the request; see [Meters](#meters).

If omitted, the request has no price limit.

**precision** `array\<enum\<string\>\>`

The weight precisions the request may be served in, at least one. Only providers that publish one of the listed precisions serve the request; a provider that publishes none never does. See [Precision values](#precision-values).

If omitted, the request may be served in any precision, including an unpublished one.

### Strategy values

`strategy` takes one of the following values. Values are case-sensitive.

| Value | Tries first |
| - | - |
| `reliability` | The provider with the best recent success rate |
| `balanced` | The fastest provider among those with a success rate close to the best |
| `latency` | The provider with the shortest time to the first token |
| `throughput` | The provider with the most output tokens per second |
| `cache` | Providers that read a cached prefix back for this model |

### Precision values

Each item of `precision` is one of `int4`, `int8`, `fp4`, `mxfp4`, `nvfp4`, `fp6`, `fp8`, `mxfp8`, `fp16`, `bf16` and `fp32`. The precisions a model's providers publish are its `precision` in [`GET /v1/models`](https://docs.naga.ac/get-started/models#read-a-model-entry).

### Meters

Each key of `max_price` is a meter from the model's `pricing` in [`GET /v1/models`](https://docs.naga.ac/api-reference/models/list-models). Each value is a non-negative decimal, as a string such as `"0.000005"` or a number. A meter that the model doesn't price is ignored, so one cap can serve several models.

| Meter | Unit |
| - | - |
| `token` | A token in either direction, for a model without a meter of its own |
| `input_token` | A prompt token, for a model without a meter of its own |
| `output_token` | An output token, for a model without a meter of its own |
| `cached_input_token` | A prompt token read from cache |
| `cache_write_input_token` | A prompt token written to cache |
| `cache_write_1h_input_token` | A prompt token cached for one hour |
| `input_text_token` | A prompt text token |
| `output_text_token` | An output text token |
| `input_audio_token` | An input audio token |
| `output_audio_token` | An output audio token |
| `input_image_token` | An input image token |
| `output_image_token` | An output image token |
| `input_audio_hour` | An hour of input audio |
| `output_audio_hour` | An hour of output audio |
| `input_text_character` | An input text character |
| `output_text_character` | An output text character |
| `input_text_search` | A rerank search |
| `output_image_image` | A delivered picture |
| `output_video_second` | A second of video |
| `output_video_megapixel_second` | A megapixel-second of video from an upscaler |

## Example object

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
{
  "strategy": "latency",
  "max_price": {
    "input_token": "0.0000005",
    "output_token": "0.0000025"
  },
  "precision": ["fp8", "bf16"]
}
```

## Related field: `service_tier`

Responses and Chat Completions also take OpenAI's [`service_tier`](https://docs.naga.ac/api-reference/responses/create-a-response#body-service-tier). Only `flex` changes routing: it uses only providers at the model's base `price`. `auto`, `default`, `scale` and `priority` route as `default`, and an unknown value isn't an error. Messages has no `service_tier`.

## Errors

A mistake in `routing` fails with `400` and `type` `invalid_request_error` before NagaAI tries a provider, so it costs nothing. A JSON body's message ends with the position in the body, such as ` at line 1 column 54`; the table leaves it out.

| You send | `message` |
| - | - |
| An unknown strategy, `{"strategy": "fast"}` | ``body.routing.strategy: unknown variant `fast`, expected one of `reliability`, `balanced`, `latency`, `throughput`, `cache` `` |
| An unknown key, `{"provider": "x"}` | ``body.routing.provider: unknown field `provider`, expected one of `strategy`, `max_price`, `precision` `` |
| `strategy` on a non-chat endpoint | ``body.routing.strategy: unknown field `strategy`, expected `max_price` or `precision` `` |
| An unknown meter, `{"max_price": {"output_widget": "1"}}` | `body.routing: max_price: unknown meter 'output_widget'; use a meter from the model's pricing in GET /v1/models` |
| A negative cap, `{"max_price": {"output_token": "-1"}}` | `body.routing: max_price.output_token: expected a non-negative decimal, got '-1'` |
| An unknown precision, `{"precision": ["fp7"]}` | ``body.routing.precision[0]: unknown variant `fp7`, expected one of `int4`, `int8`, `fp4`, `mxfp4`, `nvfp4`, `fp6`, `fp8`, `mxfp8`, `fp16`, `bf16`, `fp32` `` |
| An empty list, `{"precision": []}` | ``body.routing: precision: expected at least one value; drop `precision` to accept any`` |

A form request, such as image edits and audio uploads, reports every mistake under `body.routing: `, with no position.

When the request is valid but no provider of the model or of any fallback model is within the limit, the request fails with `400` `invalid_request_error`:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
{"error": {"type": "invalid_request_error", "message": "No provider of the 'anthropic/claude-sonnet-5.5' model serves this request within its price limit. `price` and `max_price` of the model's `pricing` in GET /v1/models give the range its providers sell at; raise `routing.max_price` or drop `service_tier: \"flex\"`."}}
```

When no provider of the model or of any fallback model publishes a precision that `routing.precision` lists, the error names the field in `param`. Messages has no `param` in its error shape, so there the message alone says it:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
{"error": {"type": "invalid_request_error", "message": "No provider of the 'anthropic/claude-sonnet-5.5' model serves it in a precision `routing.precision` lists. `precision` of the model in GET /v1/models gives the precisions it is served in; widen `routing.precision` or drop it.", "param": "routing.precision"}}
```

## See also

* [Limit the price of a request](https://docs.naga.ac/guides/limit-the-price.md): set `max_price` or `service_tier` step by step.
* [Require a precision](https://docs.naga.ac/guides/require-a-precision.md): set `precision` step by step.
* [Routing](https://docs.naga.ac/build/routing.md): how NagaAI orders providers and falls back to other models.
* [Create a response](https://docs.naga.ac/api-reference/responses/create-a-response.md#body-routing): `routing` in the generated endpoint reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.