Skip to main content

​
Response Metadata

Every response from Routor includes routing metadata so you can see which model handled your request, what tier it was classified into, and how much you saved. There are two ways to access it.

​
The routor Response Object (Always Available)

Every non-streaming response includes a routor object in the JSON body. This is the primary way to read routing metadata. It works on every deployment, with no configuration needed. 
{
  "id": "chatcmpl-abc123",
  "model": "moonshot/kimi-k2.6",
  "choices": [...],
  "usage": { ... },
  "routor": {
    "model":       "moonshot/kimi-k2.6",
    "tier":        "LIGHT",
    "profile":     "auto",
    "confidence":  0.82,
    "savingsPct":  87.4,
    "method":      "rules"
  }
}
FieldDescription
modelThe model that handled the request (may differ from the routed model if a fallback was used)
tierThe complexity tier assigned: NANO, SIMPLE, LIGHT, STANDARD, or COMPLEX
profileThe routing profile used: auto, tier, or direct
confidenceClassification confidence from 0 to 1
savingsPctSavings vs the baseline model (Claude Opus 4.8) as a percentage
methodHow the tier was decided: rules

​
Reading it in code

Node.js / TypeScript: 
const res = await fetch("https://api.routor.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ROUTOR_API_KEY}`,
    "Content-Type":  "application/json",
  },
  body: JSON.stringify({ model: "auto", messages: [...] }),
});

const data = await res.json();
console.log("Model:",     data.routor.model);
console.log("Tier:",      data.routor.tier);
console.log("Savings:",   data.routor.savingsPct + "%");
console.log("Confidence:", data.routor.confidence);
Python: 
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTOR_API_KEY"],
    base_url="https://api.routor.ai/v1",
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": prompt}],
)

# The routor object is in response.model_extra or the raw response
# depending on your SDK version. Use the raw HTTP response for direct access:
import httpx
r = httpx.post(
    "https://api.routor.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['ROUTOR_API_KEY']}", "Content-Type": "application/json"},
    json={"model": "auto", "messages": [{"role": "user", "content": prompt}]},
)
data = r.json()
print("Model:",    data["routor"]["model"])
print("Tier:",     data["routor"]["tier"])
print("Savings:",  data["routor"]["savingsPct"], "%")

​
Response Headers (Debug Mode Only)

Every response includes X-Request-Id, a unique ID for that request, useful for support queries. The X-Routor-* headers are only emitted when the server has DEBUG_ROUTING=1 set. On a default production deployment, these headers are not present. Use the routor response object above instead, which is always available.
HeaderTypeAlways sent?Description
X-Request-IdstringYesUnique ID for this request
X-Routor-ModelstringOnly with DEBUG_ROUTING=1The model that handled the request
X-Routor-TierstringOnly with DEBUG_ROUTING=1The complexity tier assigned
X-Routor-ConfidencefloatOnly with DEBUG_ROUTING=1Classification confidence from 0 to 1
X-Routor-ProfilestringOnly with DEBUG_ROUTING=1The routing profile used
X-Routor-SavingsstringOnly with DEBUG_ROUTING=1Savings vs baseline as a percentage
X-Routor-FallbackbooleanOnly with DEBUG_ROUTING=1true if a fallback model was used
X-Routor-History-FloorstringOnly with DEBUG_ROUTING=1, and only when setTier floor applied from conversation history

​
Streaming Responses

Streaming responses do not include the routor object in the stream. To get routing metadata for a streamed request:
  1. Check the dashboard, which records every request regardless of streaming
  2. Use the Debug Endpoint with the same prompt to see the decision without spending credits
  3. If your deployment has DEBUG_ROUTING=1 set, the X-Routor-* headers are sent before the stream begins

​
Fallback Indicator

When the primary model fails and Routor tries the next one in the chain, the routor object in the response body shows the fallback model (not the original routed model). If DEBUG_ROUTING=1 is set, the X-Routor-Fallback: true header is also added. A high rate of fallbacks from one provider is a sign that provider is having issues. Check the Provider Health page in the dashboard.