Two Ways to Ask for a Model: Direct, or nrouter/auto

What it does

There are two ways to ask nRouter for a model. Direct: put a model name in model and that model is called; nRouter never swaps it, and a different model answers only through a fallback you configured yourself. nrouter/auto: put nrouter/auto in model and nRouter chooses an eligible model, by Best for the task or Lowest cost.

The model string you send is the whole switch. A catalogue name such as gpt-5.4-mini is a Direct request; nrouter/auto is the other way. There is no routing header to set and no third mode. Either way you pay the served model's list price with a 0% platform fee, and the response's x-nr-model header names the model that answered.

Setup steps live in the routing quick start; the full reference is Router Settings.

The job it does for you

Most teams arrive with one of two needs, and they pull in opposite directions.

Before, teams wrote both behaviours in application code: a retry wrapper that swapped models on any error, and a hand-kept table of "cheap" and "good" models. The wrapper retried where the provider had already billed work; the table went stale with the next price change.

After, the decision lives in one string. Code that must pin a model names it; code that wants a choice sends nrouter/auto. Failover rules and price data are the gateway's job, and response headers tell you what happened.

Two things changed on 2026-10-15 that make this the whole picture. Smart Router aliases with their own strategy were withdrawn, so an alias name is now an unknown model, and per-model weights are no longer applied. Fallback lists you saved for a model keep working.

How it works

Figure 1: The model string selects the path. Direct calls the model you named; nrouter/auto chooses one.

Direct: the model you name is the model you get

When model names a catalogue model, that model is called. A different model can answer only through a fallback you set up:

1. A saved fallback list for that model, kept on the Direct tab of Router Settings, or
2. nrouter_fallbacks on the request, up to four model names, which replaces the saved list for that one call.

Even then, the next model is tried only when the provider cannot take the request:

The line is drawn where a retry does not risk a second bill to you. A refusal before any work (429, 503, 529, a deployment fault) and a connection that never opened cannot have been billed. A stalled first byte is the one case where the provider may already have started: the gateway abandons that call and nRouter absorbs whatever it cost, so you are still charged once, for the model that answered. Once response bytes have arrived, or on a 500, 502, 504 or read timeout, the request is never replayed on another model. One request takes one credit reservation and one rate-limit slot and makes at most three provider calls however far it walks.

nrouter/auto: nRouter chooses

Send nrouter/auto and nRouter chooses an eligible model from the ones your organization, team and key allow. Requests that ask for reasoning, carry a long input, or run a long tool conversation are treated as heavy and offered heavy models only. The choice follows your organization's preference:

The 2,000 ms figure bounds the decision step. It is not a promise about how fast your response arrives.

Set it up

1. Get a key. Create a virtual key in the dashboard and export it as NROUTER_API_KEY. The base URL is https://api.nrouter.ai/v1, and any OpenAI-compatible SDK works.
2. Make a Direct call. Name the model you want:

curl -sD - https://api.nrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{ "role": "user", "content": "Summarize this incident report." }],
    "nrouter_fallbacks": ["claude-sonnet-4-5", "gpt-5.5"]
  }'

3. Read the headers. A call answered by the model you named reads x-nr-routing: direct. If the first fallback answered, it reads fallback:1, the 0-based index in the chain you walked. x-nr-attempts counts provider calls and x-nr-model names the model that served it.
4. Save a standing list instead if every caller should share one. Owners and Organization Admins set a fallback list per model on the Direct tab of Router Settings; drop nrouter_fallbacks from the request and the saved list applies.
5. Switch a call to nrouter/auto by changing one string:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.nrouter.ai/v1',
  apiKey: process.env.NROUTER_API_KEY,
});

const { data, response } = await client.chat.completions
  .create({
    model: 'nrouter/auto',
    messages: [{ role: 'user', content: 'Summarize this incident report.' }],
  })
  .withResponse();

console.log(response.headers.get('x-nr-model')); // the model that answered
console.log(data.choices[0].message.content);

6. Pick the preference. Best for the task is the default. To use Lowest cost, an Owner or Organization Admin changes it on the nrouter/auto tab of Router Settings. It is an organization-wide setting; nothing in your code changes.

Do not send nrouter_fallbacks with nrouter/auto. It builds its own fallbacks, and the request is refused with 400 fallback_not_allowed.

Worked example with numbers

Lowest cost sorts on a simple figure: input price plus output price, per million tokens, weighted equally. The rates below are illustrative, not catalogue prices, so the arithmetic is easy to follow. Read the live rates on the models page.

Now cost one request that reads 10,000 tokens and writes 500, on each model:

Model A serves because its list rate is lowest, yet Model B would have billed less for this read-heavy request. That is exactly why we describe Lowest cost as ordering by list rate and never as the smallest bill: the order is set before the gateway knows how many tokens you will read or write. For a write-heavy request the comparison flips the other way. If your traffic is reliably lopsided, name the model Direct.

What it costs

Both ways bill identically. Your organization's credit balance is charged the served model's list price, with a 0% platform fee and no per-token markup. Pay as you go starts at $5, and a purchase charges exactly the credits bought; the details are on pricing.

• Direct with fallbacks. You pay for the model that answered, once. A fallback model can cost more or less than the one you named.
• nrouter/auto. You pay the list price of the model it chose, reported on x-nr-request-cost. A fallback can cost more than the first pick.
• Refusals. A request refused before any provider call, such as one rejected with fallback_not_allowed, is not charged.

Markup-Free LLM Credits: 0% Platform Fee, Exact List Price walks through the fee arithmetic line by line.

Where it fits with the rest of the platform

Routing decides which model answers; the rest of the request path is unchanged by the choice.

For failover in depth, Provider Fallback Chains: Surviving an OpenAI Outage shows a chain riding out a real outage. 429 vs 402 on an LLM Gateway: Which to Retry, Which to Stop covers what your own client should do with the errors that come back. The hold behind "one reservation per request" is explained in Reserve-and-Settle: Never Overspend a Credit Balance.

Organizations that need these controls under dedicated tenancy or in their own cloud can talk to us about nRouter Enterprise.

Limits and what it will not do

• Direct never improves your choice. If the model you named is slow or wrong for the task, nRouter still calls it. Choosing is what nrouter/auto is for.
• No failover on 500, 502, 504 or a read timeout. These come back to you, because the provider may already have done billable work.
• At most three provider calls per request, and at most four names in nrouter_fallbacks. Every target must be a model your key can already route to; one it cannot is refused by name, never dropped.
• nrouter/auto takes no per-request fallback list. It refuses nrouter_fallbacks with 400 fallback_not_allowed.
• Lowest cost is not the lowest bill. It orders by list rate, as the worked example shows.
• The preference is organization-wide. A single request cannot ask for Lowest cost while the organization is on Best for the task.
• Smart model selection can be switched off. An Owner or Organization Admin can turn off Smart model selection under Settings → Privacy, after which the prompt is never sent to the decision step; Lowest cost keeps working, while Best for the task requests may be refused with a 400 that names the setting.
• Aliases are gone. A former Smart Router alias name now returns the unknown-model error; send a catalogue name or nrouter/auto.

Frequently asked questions

What are the two ways to ask nRouter for a model?

Direct and nrouter/auto. Direct means you put a catalogue model name in model and that model is called; nRouter never swaps it, and another model answers only through a fallback you configured. nrouter/auto means nRouter chooses an eligible model by Best for the task (the default) or Lowest cost. Either way you pay the served model's list price.

When does a Direct request fail over to another model?

Only when you configured a fallback, as a saved list for that model or nrouter_fallbacks on the request, and only when the provider cannot take the request: a 429, 503 or 529, a 401 or 404 deployment fault, a connection that never opened, or a stalled first byte. A 500, 502, 504 or read timeout never fails over.

Does Lowest cost guarantee the smallest bill?

No. It orders the models fit for the task by the lowest list rate: input plus output price per million tokens, weighted equally, read live from the catalogue. It does not know your token counts in advance, so a read-heavy or write-heavy request can cost less on another model. You are billed the served model's list price.

How do I know which model answered?

Read the response headers. x-nr-model names the model that served the request. x-nr-routing reads direct when the first model in the chain answered and fallback:<n> when the entry at 0-based index n did. x-nr-attempts counts provider calls.

What happened to Smart Router aliases?

They were withdrawn on 2026-10-15. A request that names a former alias now returns the unknown-model error. Send a catalogue model name for Direct, or nrouter/auto to have nRouter choose. Fallback lists you saved for a model keep working.

Try it

Pay as you go starts at $5 with a 0% platform fee: create an account at app.nrouter.ai/signup, make one Direct call and one nrouter/auto call, and compare x-nr-model on the two responses. The routing quick start has the five-minute version, and nrouter.ai has the wider platform.

See also

• Provider Fallback Chains: Surviving an OpenAI Outage — a fallback list working through a real provider outage, the Direct path's safety net in practice.
• 429 vs 402 on an LLM Gateway: Which to Retry, Which to Stop — what your client should do with the errors the gateway hands back instead of failing over.
• Reserve-and-Settle: Never Overspend a Credit Balance — why a request that walks three models still takes one hold and one charge.
• Markup-Free LLM Credits: 0% Platform Fee, Exact List Price — the billing that applies identically to both ways of asking.
• Cost Honesty: Unpriced Is Never $0 on Your LLM Bill — why nrouter/auto never chooses a model without a usable price.
• Router Settings reference — every field on the Direct and nrouter/auto tabs.

Sources

Verified 2026-10-15. If something has drifted, email hello@nrouter.ai.

• HTTP 429 Too Many Requests: RFC 6585 §4
• HTTP 500, 502, 503 and 504 semantics: RFC 9110 §15.6
• Anthropic 529 overloaded_error: docs.anthropic.com/en/api/errors
• OpenAI chat completions request shape: platform.openai.com/docs/api-reference/chat
• OpenAI Node SDK withResponse() for headers: github.com/openai/openai-node