# Provider routing

Choose which providers serve your request, and in what order.

1. [Find a model's providers](#1-find-a-models-providers).
2. [Sort or pin them](#2-sort-or-pin-them).
3. [Hold the request to what you need](#3-hold-the-request-to-what-you-need).

A request that names no routing goes to the cheapest provider that serves its model first. Everything below is for when that is not what you want.

## 1. Find a model's providers

One model can be served by several providers. [One model's providers](/docs/reference/endpoints) lists them for a model: each entry holds a `tag`, the provider's name for routing, and the request fields it honours.

## 2. Sort or pin them

Add a `provider` object to the request. Each field narrows or orders the providers tried.

| Field | Holds |
|---|---|
| `sort` | the order to try them in: `price`, `throughput`, `latency` or `exacto` |
| `order` | provider tags, tried in this order |
| `only` | provider tags; no other provider serves the request |
| `ignore` | provider tags that never serve the request |
| `allow_fallbacks` | `false` to stop at the providers you named, `true` to let the next one serve when they fail |

`sort` also takes an object, `{"by": "latency", "partition": "none"}`: `partition` is `model` to sort within each model, or `none` to sort every provider together, across the models you named.

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Write a one-line welcome for a bakery in Tlemcen."

body = {
    "model": MODEL,
    "provider": {"sort": "latency", "allow_fallbacks": True},
    "messages": [{"role": "user", "content": PROMPT}],
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    reply = json.load(response)

print(reply["choices"][0]["message"]["content"])
print(reply["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "Write a one-line welcome for a bakery in Tlemcen.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    provider: { sort: "latency", allow_fallbacks: true },
    messages: [{ role: "user", content: PROMPT }],
  }),
});
const reply = await response.json();

console.log(reply.choices[0].message.content);
console.log(reply.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address = "https://opendunes.com/v1/chat/completions"
	model   = "anthropic/claude-sonnet-4.5"
	prompt  = "Write a one-line welcome for a bakery in Tlemcen."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model": model,
		"provider": map[string]any{
			"sort":            "latency",
			"allow_fallbacks": true,
		},
		"messages": []any{
			map[string]any{"role": "user", "content": prompt},
		},
	})
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+apiKey)
	request.Header.Set("Content-Type", "application/json")

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	var reply struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			Cost float64 `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(response.Body).Decode(&reply); err != nil {
		panic(err)
	}
	fmt.Println(reply.Choices[0].Message.Content)
	fmt.Println(reply.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
PROMPT="Write a one-line welcome for a bakery in Tlemcen."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "provider": {
      "sort": "latency",
      "allow_fallbacks": true
    },
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ]
  }'
```

A pinned provider is charged at that provider's price, not the cheapest one's: `usage.cost` is the charge of the provider that served.

When you only want one ordering, a suffix on the model name says it in a word:

| Write | Tries first |
|---|---|
| `anthropic/claude-sonnet-4.5:nitro` | the fastest providers |
| `anthropic/claude-sonnet-4.5:floor` | the cheapest providers |
| `anthropic/claude-sonnet-4.5:exacto` | the providers whose tool calls are the most reliable |

Suffixes combine. Among `:nitro`, `:floor` and `:exacto`, the last one wins.

<div class="do">
<p>Leave <code>allow_fallbacks</code> at <code>true</code> unless one provider is a hard requirement. With <code>false</code>, a provider that is down fails your request.</p>
</div>

<div class="dont">
<p>Don't confuse it with <a href="/docs/fallbacks">Fallbacks</a>. <code>allow_fallbacks</code> moves on to another provider of the same model; <code>models</code> moves on to another model.</p>
</div>

## 3. Hold the request to what you need

| Field | Holds |
|---|---|
| `max_price` | an object of numbers, none below zero: the most you will pay, in DA per million tokens, for each meter the model has. A provider above it is not tried |
| `require_parameters` | `true` to try only the providers that honour every field of your request |
| `data_collection` | `"deny"` to try only the providers that do not keep your data |

The settings of your account bind every request. A request's own `provider` wins field by field, and may add a restriction, but never lift one the account holds.

<div class="watch-out">
<p>When no provider meets what you asked for, the request fails with a 503. Loosen one field, or name more providers.</p>
</div>

## Errors

The body says why. What to do on every status: [Errors and retries](/docs/errors-and-retries).

| Status | Means |
|---|---|
| 400 | the `provider` object holds a field it does not know, or a value of the wrong kind |
| 402 | the balance cannot cover the request |
| 404 | no such model |
| 503 | no provider meets the routing you asked for |
