Smart Routing: Route every request to the right model.

Direct mode uses the customer’s own fallbacks: a stalled call fails over inside the same credit hold before the first byte arrives. Only the answering candidate is billed at published list price, while previous failed attempts cost $0.

When a model provider experiences an outage, rate limit (429), or overload (503), nRouter routes the request to your next configured fallback model within the same credit hold and bills only the model that answers. Failover happens before the first byte; once a stream has started, a provider failure ends that response rather than switching models mid-stream.

Direct: you choose the model. nRouter never swaps it for another; a different model answers only through a fallback you configured yourself (a fallback list for that model in Router Settings, or nrouter_fallbacks on the request), and only when the provider cannot take the request. nrouter/auto: nRouter chooses an eligible model for you. Best for the task (the default) uses smart model selection when it is available; Lowest cost orders the models fit for the task by their list rate. Either way you pay the served model’s list price, and x-nr-model names it.

The response names it. The x-nr-model response header, the model field in the response body and every streamed frame carry the model that served the request; nrouter/auto appears there only when no provider answered. The response also carries the cost, the token counts and the routing outcome: x-nr-request-cost, x-nr-cost-status, the token headers, x-nr-routing and x-nr-attempts.

The gateway moves to the next model in the chain when the provider is rate limited (429) or overloaded (503 or 529), when it rejects with a 401 or 404, when the connection fails, or when an attempt sends nothing before its first-byte time limit and another model is left to try. It does not fail over on a 500, 502 or 504, or once the response has started, because the provider may already have done the work. A fallback list you save for rate limits only, or for errors only, is used only for that kind of failure.

No. One request holds credit once and settles once, at the price of the model that answered. You are not billed for attempts that failed over.

The Owner and Organization Admins. Fallback lists and the nrouter/auto preference are edited in Router Settings and apply to the whole organization, not to a single key or team. Members and viewers can read them but cannot change them.

Start with the x-nr-request-id response header. The same response carries x-nr-model, x-nr-routing (direct, or fallback:<n>), x-nr-attempts, the cost headers and the token counts. In the dashboard Logs, the row for that request id shows the model that served it, the cost, and a routing record with attempts, served_rank, fallback_used and source.

Set the nrouter/auto preference for your organization in Router Settings, or send nrouter_optimize: "quality" or "cost" on a single request. Best for the task is the default. Lowest cost orders the models fit for the task by list rate: input price plus output price per million tokens, weighted equally. Either way the request is billed at the served model’s list price.

Yes. Add the body field nrouter_fallbacks: an array of up to 4 distinct model ids that does not repeat the requested model. It replaces your organization’s fallback list for that one call. On nrouter/auto it replaces the fallbacks nrouter/auto would choose: its chosen model is tried first, then yours. A request makes at most 3 provider calls by default, so later entries may not be reached. A target you cannot use returns a 400 with the code fallback_not_allowed. On nrouter/auto, a model your organization, team or key denies returns a 403.

No. A model is served on the endpoint its provider supports. For example, Claude models are served on the Messages endpoint. The model list shows which endpoints each model serves, and a fallback must serve the endpoint you call.

A name the catalogue does not publish is refused as an unknown model. A direct request is never silently sent to a model you did not choose: only a fallback you configured can answer instead, and only when the provider cannot take the request.

At the exact list price of the model that served the request, paid from your credits with zero token markup. For existing subscribers, requests draw from their plan allowance first. The x-nr-funding-source response header indicates the source: allowance or credits.

Yes, with one difference. nrouter/auto always runs the built-in checks on prompts and outputs, and every guardrail your organization configured still applies. The platform’s model-scored moderation and prompt-injection checks run when you name a model directly; they are not added to nrouter/auto requests. To have them on nrouter/auto, add them as your own guardrails.