Response headers
Every response to /v1/chat/completions carries a set of X-SI-* headers. They are your per-request receipt. Read them in code, log them in your ops stack, or just check them in the dashboard.
- X-SI-Cost - estimated cost in USD for this request
- X-SI-Score - routing score of the chosen provider
- X-SI-Candidates - how many providers were evaluated
- X-SI-Model and X-SI-Provider - routing identifiers (diagnostic, not a stable contract)
- X-SI-Spot and X-SI-Interruption-Risk - present when the request landed on reclaimable capacity
The header table
| Header | Always present? | Example | Meaning |
|---|---|---|---|
X-SI-Cost |
Yes | 0.00042 |
Estimated cost for this request in USD. This is the price you pay, matching the rates shown in /v1/pricing. |
X-SI-Score |
Yes | 0.8734 |
Quality score for this route. Higher is better. See routing. |
X-SI-Candidates |
Yes | 5 |
Number of providers considered after filtering. If this is low, coverage for that model is thin. |
X-SI-Model |
Yes | meta-llama/... |
The model identifier used for this request. Useful in support tickets. |
X-SI-Provider |
Yes | provider-a |
Routing ID. Not a brand name and not a stable contract. |
X-SI-Spot |
Yes | true / false |
Whether the request ran on reclaimable (preemptible) capacity. |
X-SI-Interruption-Risk |
Only when X-SI-Spot is true |
0.12 |
Probability (0.0-1.0) that this capacity gets reclaimed mid-request. |
All headers are set on both streaming and non-streaming responses.
Reading headers in code
Python (requests)
import requests
r = requests.post(
"https://smart.aivory.net/v1/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json={...},
)
cost = r.headers.get("X-SI-Cost")
score = r.headers.get("X-SI-Score")
TypeScript (fetch)
const res = await fetch("https://smart.aivory.net/v1/chat/completions", {
method: "POST",
headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
body: JSON.stringify({ /* ... */ }),
});
const cost = res.headers.get("X-SI-Cost");
const score = res.headers.get("X-SI-Score");
Python (OpenAI SDK)
The OpenAI SDK hides raw headers by default. Use the with_raw_response variant:
raw = client.chat.completions.with_raw_response.create(
model="llama-3.3-70b",
messages=[...],
)
cost = raw.headers.get("X-SI-Cost")
result = raw.parse()
Using the headers
- Log them.
X-SI-CostandX-SI-Candidatesper request makes cost and coverage regressions obvious in aggregate. - Alert on thin coverage. If
X-SI-Candidatesfor a popular model drops below 2, coverage is about to get fragile. - Retry policy.
X-SI-Spot: truetells you the request ran on reclaimable capacity. If stability matters more than cost, consider retrying or using a different model.
What’s not a stable contract
- The literal value of
X-SI-Provider. We may rename routing identifiers at any time; treat it as opaque. - The exact numeric range of
X-SI-Score. Don’t compare scores across different models or time periods. - Additional
X-SI-*headers may appear. Ignore unknown ones.