Opting in
The response cache is off by default. Set x-openrouter-cache: true
on a request to enable it — an exact repeat of the same messages/params, from the same account, returns the
stored completion without calling a provider:
curl https://api.llmrouter.sh/v1/chat/completions \
-H "Authorization: Bearer llmr_sk_live_..." \
-H "x-openrouter-cache: true" \
-H "x-openrouter-cache-ttl: 600" \
-H "content-type: application/json" \
-d '{"model": "auto", "messages": [{"role": "user", "content": "..."}]}'
x-openrouter-cache-ttl overrides the write
TTL in seconds (1–86400, default 300); x-openrouter-cache-clear: true
forces a fresh upstream call and re-writes the entry, without disabling the cache going forward. The cache is
always namespaced to your org — two accounts never share an entry, even on a byte-identical prompt.
Request & response headers
| Header | Direction | Meaning |
|---|---|---|
| x-openrouter-cache | request | enable caching for this request |
| x-openrouter-cache-ttl | request | write TTL in seconds, 1–86400 |
| x-openrouter-cache-clear | request | force a fresh call, re-write the entry |
| x-openrouter-cache-status | response | HIT or MISS — non-streaming responses only |
| x-openrouter-cache-ttl | response | the TTL actually applied to this entry |
What's excluded
Requests carrying tools or the legacy
functions field never touch the response
cache, opt-in or not — a cached tool call could reference stale state, so this is a hard skip rather than a
toggle. Because a cache hit replays one frozen sample, treat it as best suited to
temperature: 0-style deterministic
traffic; on higher-temperature traffic a hit will keep returning the first answer that was ever sampled for
that exact prompt until the TTL expires.
Provider prompt caching
Separately from the opt-in cache above, providers with their own prompt/prefix caching (e.g. Anthropic, OpenAI)
are used automatically — no header needed. When a request lands on the same underlying provider node as a
previous call with the same prefix, the provider itself charges less for the repeated tokens; that saving is
surfaced back to you as usage.cache_discount
whenever it applies. Passing a stable session_id
in the request body (or an x-session-id header)
for a multi-turn conversation improves the odds consecutive calls land on the same node, raising this hit rate.