# Routing and routes

Every model you call through kenari is routed automatically. When you want to decide the order yourself, build a named route in the dashboard and send its name in the `model` field. Your client code does not change either way.

## Automatic routing

For each model, kenari picks a healthy provider and sends your request there. If that provider returns an error, hits a limit or is slow, kenari moves on to the next one. Within a session, kenari tends to keep you on the same provider while it stays healthy, so latency and output style stay steady.

You do not configure anything, and responses never reveal which provider served a request. See [Errors](/en/docs/errors) for what you see when every provider fails.

## Named routes

A route is an ordered list of steps. Each step is one model plus one credential: a key or a subscription connection you added under [Providers](/en/docs/byok), or **kenari balance (PAYG)**. You call the route by name, and kenari works through the steps for you.

Routes work on [Chat completions](/en/docs/chat), [Messages](/en/docs/messages) and [Responses](/en/docs/responses). Only chat models can be steps. Image, audio, embedding, rerank and moderation models cannot.

### Create a route

1. Open **Providers & Routes** in the dashboard, then the **Routes** tab.
2. Click **Create Route**, then choose **Custom route**.
3. Enter a **Route Name** such as `cheap-first`, and click **Create**.
4. Click **Edit** on the new route, then **Add Step** for each step. Pick a **Credential** and a **Model** for every step.
5. Click **Save**.

A route name is unique in your account and at most 64 characters. `kenari-free` and any name that starts with `byok/` are reserved.

The create dialog also offers **Per-model route**, which builds a route for one model: it tries your eligible API keys first, then kenari. You need an API key on the **Providers** tab first.

### Choose a strategy

The **Strategy** setting decides which step kenari tries first. If a step fails or hits a limit, kenari continues with the remaining steps.

| Strategy | First step on each request |
| --- | --- |
| **Fallback** | Always step 1. Later steps are used only when earlier ones fail. This is the default. |
| **Round Robin** | The next step in turn, so requests rotate through the list. |
| **Random** | A random step. |
| **Weighted** | A step picked at random in proportion to its **Weight**. |
| **Latency** | The step with the lowest recent latency. Steps with no latency data yet are tried first. |

### Call a route

Send the route name as `model`, exactly like a model id.

```bash
curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cheap-first",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

Because a route only changes the `model` value, you can reorder steps or add a backup without touching client code.

### Common patterns

| Pattern | Steps | Use when |
| --- | --- | --- |
| Own key first | Step 1: your own API key. Step 2: **kenari balance (PAYG)** | You want to spend your provider quota first and keep kenari as a backup. |
| Subscription first | Step 1: a connected subscription, such as ChatGPT, with the provider's model id. Step 2: **kenari balance (PAYG)** | You want to use the allowance you already pay for and continue on your balance when it runs out. See [Providers](/en/docs/byok#use-a-connection-in-a-route). |
| Cheapest first | Step 1: a low-cost model. Step 2: a stronger model as an availability backup | You want the low-cost model for every request and a stronger model only when it fails or hits a limit. Choosing a model by task difficulty needs logic in your own app. |
| Spread load | Strategy **Round Robin** over several keys | You want to share traffic across keys. |

### The kenari-free route

Every account has a read-only route named `kenari-free` that serves free models. See [Free models](/en/docs/free-models).

## Limits and pitfalls

- A malformed request, such as an invalid body, is returned as an error right away. kenari does not retry it on later steps because every step would reject it too.
- A step whose key or connection is disabled, deleted, paused, signed out or lapsed is skipped.
- Named routes are not available on a key with a spend cap, a token cap or a model restriction. The request returns `400`. Use an unrestricted key, or see [Authentication and API keys](/en/docs/authentication).
- Steps that use **kenari balance (PAYG)** are charged by the funding rules that apply to the step's model, so an eligible step can be covered by plan quota or cost nothing on a free model. Otherwise it is billed to your balance. Steps that use your own key are billed by your provider. See [How billing works](/en/docs/billing).

## See also

- [Providers](/en/docs/byok)
- [Free models](/en/docs/free-models)
- [Errors](/en/docs/errors)
- [Authentication and API keys](/en/docs/authentication)