OpenRouter prompt caching: fix cache misses and check costs

OpenRouter cache not working? Use this page to find out whether your model supports the caching behavior you expect, why cached_tokens is zero or missing, what to change in requests or routing, and whether a cache hit actually reduced total cost.

Jump to troubleshooting failure modes or run the verification script (three paid API calls — optional).

How do I verify that a request actually used the cache?

Cache usage is provider prompt caching — not response caching  (identical full-body replay) and not semantic caching (your middleware). You are looking for prefix reuse reported in the API usage object or Activity detail.

Evidence to inspect

{
  "usage": {
    "prompt_tokens": 10339,
    "completion_tokens": 60,
    "cost": 0.0123,
    "prompt_tokens_details": {
      "cached_tokens": 10318,
      "cache_write_tokens": 0
    }
  },
  "cache_discount": 0.0041
}

Missing field vs explicit zero

A cache hit (cached_tokens > 0) is evidence of prefix reuse, not proof of net savings. Compare usage.cost and Activity rows before and after your fix.

Does my model and provider support caching?

OpenRouter forwards to upstream providers. Behavior is not universal — verify your exact model slug in the OpenRouter prompt caching guide  (verified 2026-09-09).

Router models (openrouter/auto, Pareto, Fusion) may resolve to different upstream models between turns. Sticky routing reuses the resolved model only while it stays in the candidate set — not a guarantee of cache continuity.

If you are unsure whether caching is enabled for your slug, run the verification script on that model or inspect one generation in Activity before changing application code.

Why is cached_tokens zero or missing?

Each row is symptom → evidence → fix → verification. Provider rules come from OpenRouter prompt caching docs ; observed API output is authoritative for your account.

Prefix shorter than provider minimum

Reusable prefix changes every request

Cache expired (TTL)

Provider drift between turns

OpenRouter activates sticky routing on any successful request when session_id is set — even before a cache hit — so later turns route to the same provider (sticky routing docs ).

Manual provider.order or forced routing

Sticky routing is disabled when you set provider.order — OpenRouter docs, 2026-09-09.

Explicit caching required but not set

Client-side request transformation

Wrong cache type diagnosed

What should I change in my request or routing configuration?

Stable prefix layout

┌─────────────────────────────────────┐
│ REUSABLE PREFIX (cache candidate)   │
│  system prompt, tools, rules, RAG   │
├─────────────────────────────────────┤
│ DYNAMIC SUFFIX                      │
│  user message, session tool results │
└─────────────────────────────────────┘

1. Static first — system prompt, tool definitions, stable rules
2. Dynamic last — user messages, retrieved chunks, run-specific state
3. Do not edit the system block every agent turn in IDE or agent clients

session_id for agents and automation

{
  "model": "anthropic/claude-sonnet-4",
  "session_id": "workflow-invoice-review-42",
  "cache_control": { "type": "ephemeral" },
  "messages": [
    { "role": "system", "content": "<STABLE RULES AND REFERENCE TEXT>" },
    { "role": "user", "content": "<TASK FOR THIS STEP>" }
  ]
}

Sticky sessions expire after ~10 minutes of inactivity; each successful request resets the timer. If the sticky provider errors, the next request may re-route (OpenRouter docs ).

For routing and fallback arrays that affect provider choice, see Model routing.

Explicit breakpoints (Anthropic, Gemini large bodies, Alibaba)

{
  "model": "anthropic/claude-sonnet-4",
  "messages": [
    {
      "role": "system",
      "content": [
        { "type": "text", "text": "You are a code reviewer. Rules: ..." },
        {
          "type": "text",
          "text": "<LARGE STABLE CORPUS>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "user", "content": "Review this diff..." }
  ]
}

Gemini treats the first system message as a single immutable systemInstruction — put dynamic tail content in a later user message, not after a cached block inside system (OpenRouter Gemini section ).

How do I check whether the cache reduced my total cost?

Cache reads usually lower input cost; cache writes can increase it on the warm request.

Compare billed cost, not just cached_tokens

Illustrative cost math (not measured here)

Assumptions (Anthropic Claude Sonnet-class, OpenRouter docs 2026-09-09): base input $3 / MTok**, cache read **0.1×** input (**$0.30 / MTok), cache write 1.25× input ($3.75 / MTok). Rates vary by model — check openrouter.ai/models .

A single warm request can cost more than an uncached one. Savings appear when the same prefix is reused enough times before TTL expiry. Always use Activity cost as billing truth — see Activity & keys.

Run a minimal cache verification example

The repo ships a bounded script that makes three chat completions (charges apply). It uses anthropic/claude-sonnet-4 with top-level automatic cache_control and a >1,024-token stable system prefix — a configuration documented in OpenRouter’s Anthropic section .

Download or copy: openrouter-cache-verify.mjs  (also at public/examples/openrouter-cache-verify.mjs in the wiki repo).

# From a clone of https://github.com/narevai/tokenminning-wiki
export OPENROUTER_API_KEY="sk-or-..."   # never commit or paste into the wiki
node public/examples/openrouter-cache-verify.mjs

Optional environment variables:

The script runs, in order:

1. Warm — stable prefix, question A (may show cache_write_tokens > 0)
2. Reuse — same prefix, question B (often shows cached_tokens > 0 — not guaranteed)
3. Compare — changed prefix (expect lower or zero cache reads)

It prints generation id, model, provider (when returned), token counts, cache fields, cost, and a curl template for GET /api/v1/generation.

Live API verification is opt-in. CI and normal pnpm check do not call OpenRouter. Without your API key, validate syntax locally only — runtime cache behavior remains unverified on your account until you run the script.

Agent and automation checklist

1. Confirm the model slug supports your caching mode (automatic vs explicit cache_control)
2. Pin system prompt + tool schemas across steps in the workflow
3. Set session_id per conversation or job
4. Inspect cached_tokens after the warm request — not only on turn 1
5. Compare Activity cost before and after prefix stabilization
6. Trim MCP/rules bloat in IDE clients — OpenCode MCP

Related

• OpenRouter hub — spending checklist
• Activity & keys — billing truth and generation IDs
• Model routing — fallbacks and provider.order
• Prompt caching — provider-agnostic prefix rules
• Semantic caching — separate from cached_tokens
• OpenRouter: Prompt caching  (source of provider tables above, verified 2026-09-09)
• Response caching