Skip to main content
A route maps a name to a set of targets under a selection strategy. When a request calls the route, to11 picks one of the route’s targets according to the strategy and proxies the request using the stored credential — managed routing, rather than the caller’s own key. You create and edit routes in the dashboard, under Project → AI Gateway → Routing.

​
How a request reaches a route

A request reaches a route only by naming it in the model field:
  • route::<name> — the route’s name, as saved when you created it. function::<name> reaches the same route.
  • An endpoint kind — each route is tied to one: chat, embeddings, audio_speech, audio_transcription, or image_generation. Calling a chat route from the embeddings endpoint is rejected.
A bare model name such as gpt-4o never matches a route, even one whose targets use that model.

​
Strategies

When you create a routing rule, you choose how to11 picks among its targets. Routes offer four strategies:

​
Direct routing

A single target. Every matching request goes to the same model-and-credential pairing. This is what you get when a rule has exactly one target.

​
Weighted split

Two or more targets, chosen at random in proportion to their weights. Useful for a gradual migration (shift a slice of traffic to a new provider) or cost shaping (send most traffic to a cheaper endpoint). In the dashboard you enter each target’s share as a percentage — 70 and 30 send roughly seven requests to the first target for every three to the second.
Weighted split chooses purely by weight; it does not track the health of a target between requests. If you want failover when a target is unreachable, use a Fallback chain.

​
Fallback chain

Two or more targets tried in the order you declare them. to11 sends to the first target; on a connection error or a 5xx response it moves to the next, and so on down the chain.

​
A/B experiment

Two or more model variants, each taking a share of traffic, so you can compare them on live requests. See A/B experiment.

​
Where routes are built

You build routes in the dashboard’s AI Gateway → Routing section, where a rule pairs a name and endpoint kind with a strategy and its targets. For step-by-step walkthroughs, see the routing how-tos: Direct routing, Weighted split, Fallback chain, and A/B experiment.

​
Retries

When a request fails in a way to11 can retry, the gateway retries internally — by default up to 2 retries with a 500 ms base backoff that grows on each attempt. Retries happen inside the gateway; you do not configure them per request.

​
How routes fit into routing

A route is the managed-routing layer (L2). The request’s model field decides the layer on its own:
  • Route (L2) or function (L3) — route::<name> or function::<name>.
  • Provider (L1) — <provider-slug>::<model>, or a bare model with the x-to11-provider-id header: passthrough to that provider. See Passthrough.
A bare model with no header returns a 400. A target can name any model id, but the provider’s access policy still decides whether it is served: a target whose model is blocked, or not allowed, in the request’s environment is skipped, and when no target is left the request returns a 404. The gateway forwards a request to the selected target as written and does not translate between wire formats, so every target of a route should be on a provider that speaks the format your application sends. A request that lands on a target whose provider speaks another format is rejected with 400 and x-to11-error-code: cross_dialect. See Which SDK to call a provider with.
To call a route by a stable name and swap the model behind it without changing your application, give the route a routing identifier and invoke it as route::<name>. See Route by a stable name.

​
Example request

Call the route by name. A route named summarize:
to11 selects one of the route’s targets and uses the stored credential. The caller sends no provider key.

​
Next steps

Functions

Named task aliases that decouple caller intent from model choice.

Targets

How targets pair a model with a stored credential.

Routing overview

Managed routing, passthrough, and the resolution flow.