Routing

Model routing

Set model to "auto" and Neural Router scores eligible models against your objective and policies, then dispatches to the best one, with an explainable readout of why.

Objectives

The route.objective field decides what "best" means:

quality-per-dollar: Best quality for the price, the default balance.
lowest-cost: Cheapest eligible model that meets your constraints.
lowest-latency: Fastest to first token within the quality floor.
highest-quality: Top-scoring model regardless of price.

A request-level objective overrides the workspace default you configure under Routing.

Routing headers

Per-request routing is set with headers, so the request body stays byte-for-byte OpenAI-compatible and any OpenAI SDK can send it unmodified.

request headers

X-NR-Objective: quality-per-dollar   # or lowest-cost | lowest-latency | highest-quality
X-NR-Allow: gpt-4o,claude-sonnet     # restrict this request's candidate set
X-NR-Pin: claude-sonnet              # force one model, bypassing selection
X-NR-Preset: support-agent@3         # name, name@version, or name|env

X-NR-Allow narrows the candidates the router may choose between; X-NR-Pin takes precedence over it and selects a single model outright. Fallback order is configured on the workspace policy rather than per request.

Explainability

Every routed response carries headers describing the decision: the model that served it, why that route was chosen, the router's own overhead, and a trace id to quote in support requests.

response headers

X-NR-Model: claude-sonnet
X-NR-Route-Reason: best quality-per-dollar within latency budget
X-NR-Overhead-Ms: 7
X-NR-Trace-Id: nrq_8f2a1c4b
X-NR-Cache: miss

Provider selection

Model routing chooses which model; provider routing chooses which endpoint serves it. Combine both, see Provider routing.