OpenRouter prompt caching

OpenRouter prefix caching (and provider-side prompt caching) discounts input tokens when the start of your prompt matches a cached prefix. OpenRouter returns cache metrics on every response — no extra API flag required for basic accounting.

This page answers openrouter prefix caching, openrouter cache, and openrouter prompt caching.

Hub: Tokenminning with OpenRouter. Concept stack: Prompt caching.

Read cache metrics

Every response includes usage.prompt_tokens_details:


{
  "usage": {
    "prompt_tokens": 10339,
    "completion_tokens": 60,
    "prompt_tokens_details": {
      "cached_tokens": 10318,
      "cache_write_tokens": 0
    }
  }
}

Field	Meaning
`cached_tokens`	Tokens read from cache — >0 means cache hit
`cache_write_tokens`	Tokens written on first request establishing cache
`cache_discount`	Cost effect of cache (response body when present)

Also visible on Activity detail rows and GET /api/v1/generation.

Why `cached_tokens` stays zero

Cause	Fix
Prompt too short for provider minimum	Longer stable prefix (system + tools)
System prompt changes every turn	Stabilize AGENTS.md, rules, MCP schemas
Cache expired	Provider TTL; resend same prefix
Provider drift between turns	Set stable `session_id` for sticky routing
Client reshuffles message order	Static system block first, dynamic user content last

Stabilize the prefix

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

OpenCode/Cursor/Devin MCP and rules bloat hurts caching as much as raw tokens — trim MCP before chasing cache flags.

Explicit caching (Anthropic and others)

Some providers need cache_control on content blocks. OpenRouter supports:

Automatic top-level cache_control — advances breakpoint as conversation grows (Anthropic direct routing)
Explicit per-block breakpoints — fine-grained control (max four breakpoints)

See OpenRouter prompt caching guide .

For multi-turn agent work, set a stable session_id so routing stays on a provider that retains your cache.

Agent workflow checklist

Pin system prompt + tool schemas across turns in the session
Set session_id per conversation or workflow
Inspect cached_tokens after turn 3+ — should climb in stable chats
Compare cost in Activity before/after stabilizing rules

vs semantic caching

Layer	Matches	OpenRouter field
Prefix / prompt caching	Exact prefix reuse	`cached_tokens`
Semantic caching	Similar meaning	Separate app layer — Semantic caching