Per-Request Options
Control fallback models, active guardrails, and response caching per call using nrouter_fallbacks, nrouter_guardrails, and nrouter_cache control fields.
nRouter per-request options let you override fallback chains, attach additional pre-call guardrails, bypass response caching, or select routing optimization targets dynamically within individual inference payloads without changing organization-level dashboard settings. The gateway evaluates and strips all nrouter_* control parameters before forwarding payloads to upstream providers across /v1/chat/completions, /v1/messages, /v1/responses, and /v1/completions.
Parameter Overview
| Field | Type | Limits | Purpose |
|---|---|---|---|
nrouter_fallbacks | array of strings | 1–4 model IDs ([] allowed on nrouter/auto only) | Overrides the organization's saved fallback sequence for this single request. |
nrouter_guardrails | array of strings | 1–8 guardrail IDs or names | Adds pre-call guardrails owned by your organization to this call's chain. |
nrouter_cache | boolean | — | When false, bypasses response cache lookup and prevents storing the response. |
nrouter_optimize | "quality" | "cost" | nrouter/auto only | Overrides the organization's default selection objective for nrouter/auto calls. |
Unrecognized keys beginning with nrouter_ return 400 invalid_request. All nrouter_* parameters are stripped before forwarding to upstream providers.
Dynamic Fallback Chains (nrouter_fallbacks)
{
"model": "gpt-5.4-mini",
"messages": [{ "role": "user", "content": "Summarize this incident report." }],
"nrouter_fallbacks": ["claude-sonnet-4-5", "gemini-2.5-pro"]
}- Overrides: The list overrides saved fallbacks for that call; on
nrouter/autoit replaces the fallbacksnrouter/autowould choose (pass[]to disable auto-fallbacks). Inaccessible targets return400 fallback_not_allowed. - Failover Triggers: Failover executes only on an upstream
429,503or Anthropic529, a401or404from a misconfigured provider deployment, a connection that never opened, or a provider that sends no first byte in time. Upstream500,502,504, or post-first-byte read timeouts return as-is to avoid duplicate compute generation. - Billing: One credit reservation covers the chain (capped at 3 attempts), settling at the served model's list price.
Dynamic Guardrails (nrouter_guardrails)
{
"model": "gpt-5.4-mini",
"messages": [{ "role": "user", "content": "Draft a reply to this customer." }],
"nrouter_guardrails": ["pii-strict"]
}- Add-Only: Requests can add up to 8 organization-owned guardrails; they cannot disable standing rules or the platform safety floor.
- Refusal: Tripped guardrails halt immediately (
400,x-nr-guardrails: blocked), incurring $0 spend on blocked requests.
Cache Bypass (nrouter_cache)
{
"model": "gpt-5.5",
"messages": [{ "role": "user", "content": "Fetch real-time transaction status." }],
"nrouter_cache": false
}nrouter_cache: false prevents cache lookup and response storage, confirmed via x-nr-response-cache: bypass.
Response Headers & Telemetry
x-nr-routing: fallback:1
x-nr-attempts: 2
x-nr-response-cache: bypass
x-nr-guardrails: pass
x-nr-request-cost: 0.001420x-nr-routing: fallback:1: First fallback answered at 0-based chain index 1.x-nr-attempts: Provider attempts made.x-nr-request-cost: Precise settlement cost.
Next Steps
Router Settings · Guardrails · Observability & Logs · Chat Completions