Per-Request Options

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

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/auto it replaces the fallbacks nrouter/auto would choose (pass [] to disable auto-fallbacks). Inaccessible targets return 400 fallback_not_allowed.
• Failover Triggers: Failover executes only on an upstream 429, 503 or Anthropic 529, a 401 or 404 from a misconfigured provider deployment, a connection that never opened, or a provider that sends no first byte in time. Upstream 500, 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.001420

• x-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

Frequently asked questions