Context caching

An agentic session — Claude Code over a repository, a long conversation, a pipeline with the same system prompt every time — sends the same context with every turn: the system prompt, tool definitions, the accumulated history. Context caching (prompt caching) keeps that repeated prefix on the model’s side: the repeated part is read from the cache at a lower price instead of paying full input again.

On long sessions this is where the savings live: on most models reading from cache costs about 10% of the input price. Writing is less predictable — it depends on the vendor, see below.

How the cache lives

The cache lives for 5 minutes with sliding renewal: every hit resets the timer. In a dense session, with turns coming without pauses, the cache survives from start to finish. After a pause longer than 5 minutes the cache expires — the first turn pays full input price plus a write surcharge, and the cache picks up again from there. That is normal and needs no action from you.

The economics

Cache read — roughly 10% of the input price. That rule holds at Anthropic, OpenAI and Google: exactly a tenth for Claude Sonnet 5, and the same for GPT-6 Astra and Gemini 3.8 Flash.

Cache write depends on the vendor, and intuition misleads here:

Vendor	Read	Write
Anthropic, OpenAI	10% of input	125% — dearer than a plain input token
Google	10% of input	~6% — cheaper than a read

At Anthropic and OpenAI the first turn pays a surcharge and breaks even on the second. At Google writing costs almost nothing, so the cache pays off immediately.

For open-weight models the rate belongs to whoever hosts the model, not to the model itself: across providers of GLM 5.3 a cache read ranges from $0.1 to $0.26 per 1M tokens at nearly identical input prices — a 2.6× spread — and not one of them publishes a write price. Per-provider prices are listed in the “Providers and prices” block on the model’s page in the catalog; to pin one, see the Provider routing guide.

For the default route the prices are in the “Cache read” and “Cache write” columns of the catalog; in the API these are pricing.cache_read_rub and pricing.cache_write_rub from GET /v1/models. A dash means no cache price is published — that is not zero and not “free”.

When the cache kicks in

Client	How caching is enabled
Mixen web chat and Telegram bot	Automatically: the session prompt gets a cache marker on its own, nothing to do
POST /v1/messages	The client places cache_control breakpoints on system blocks, tools, and messages (Claude Code and the Anthropic SDK do it themselves)
POST /v1/chat/completions, POST /v1/responses	No controlling parameters: the cache engages automatically on the request’s repeated prefix

On /v1/messages a breakpoint is a {"type": "ephemeral"} object on the chosen element. Everything before the marker gets cached, so it belongs at the end of the stable part — after the system prompt and tools, ahead of the changing tail:

{
  "model": "anthropic/claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. Rules and knowledge base: ...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Hi!"}]
}

A quirk of Gemini models

The implicit cache of Google models is pickier than other vendors’, so building your request economics on it deserves caveats:

• Only long prompts get cached — from several thousand tokens. Short requests (around 1–2 thousand tokens including the system prompt) never hit the cache at all.
• Matching checks the whole prompt, not the prefix. The same system prompt with different user questions does not produce a hit — the cache engages on near-exact repeats of the full prompt. This differs from Anthropic, OpenAI, DeepSeek, and Grok, where it is exactly the shared prefix that gets cached.
• A fresh cache entry becomes visible with a delay: the first one or two retries right after a new write may still miss.

If your request economics depend on caching (a long stable prefix, many turns), Claude, DeepSeek, and Grok behave more reliably: their caches work on the shared prefix, and the hit share there is predictable.

Cache tokens in usage

How much input came from the cache is visible in the response usage. The fields differ per protocol — and so does their meaning: that is an OpenAI-versus-Anthropic format difference, not a Mixen quirk.

Protocol	Where to look	Input field
/v1/chat/completions	usage.prompt_tokens_details.cached_tokens	prompt_tokens already includes the cache
/v1/responses	usage.input_tokens_details.cached_tokens	input_tokens already includes the cache
/v1/messages	usage.cache_read_input_tokens	input_tokens is only the NON-cached remainder; total input = input_tokens + cache_read_input_tokens

The same request — 3,660 context tokens, of which 3,644 cached — across the three protocols:

/v1/chat/completions

{
  "prompt_tokens": 3660,
  "completion_tokens": 120,
  "total_tokens": 3780,
  "prompt_tokens_details": {"cached_tokens": 3644}
}

/v1/responses

{
  "input_tokens": 3660,
  "output_tokens": 120,
  "total_tokens": 3780,
  "input_tokens_details": {"cached_tokens": 3644},
  "output_tokens_details": {"reasoning_tokens": 0}
}

/v1/messages

{
  "input_tokens": 16,
  "output_tokens": 120,
  "cache_read_input_tokens": 3644,
  "cache_creation_input_tokens": 0
}

cache_creation_input_tokens on /v1/messages is always 0: the upstream reports the read volume only and never the write volume. Pricing is unaffected — the write surcharge is already part of the request cost — but a client’s “written to cache” stat will stay empty.

Add the input fields once, per the protocol’s semantics: adding cached_tokens on top of prompt_tokens in an OpenAI-format response counts the cache twice.

Getting the most out of the cache

• Keep the prefix stable. A hit requires an exact prefix match: the system prompt and tool definitions must come in the same order and unchanged from request to request. Editing the first line of the prompt or reshuffling the blocks voids the hit.
• Place the breakpoint after the stable part. On /v1/messages everything before the marker is cached: the system prompt, tools, the head of the history. Leave the fast-changing tail after it.
• Run sessions densely. Turns without pauses longer than 5 minutes keep the cache alive through sliding renewal. Every break past the TTL means full input price plus a fresh write all over again.

Example: a 10-turn agentic session

An estimate at Claude Sonnet 5 showcase prices (per 1M tokens): input $2.35, output $11.7283, cache read $0.23, cache write $2.93. Take live values from GET /v1/models — showcase prices move.

The scenario: a system prompt with tools — 10,000 tokens, unchanged; every turn adds 2,000 tokens of context and 1,000 tokens of output. Turn 1 writes the context to the cache; turns 2–10 read the accumulated prefix from the cache — 10,000 + 2,000 × (k−1) tokens on turn k, 180,000 in total; each turn’s 2,000 new tokens are billed at the full input price.

Item	Tokens	₽ per 1M	Cost
Cache write (turn 1)	10,000	267.30	≈ $0.03
Cache read (turns 2–10)	180,000	21.40	≈ $0.04
Fresh input (2,000 per turn)	20,000	213.90	≈ $0.05
Output (1,000 per turn)	10,000	1,069.50	≈ $0.12
Total with cache			≈ $0.24

Without the cache, the same 10 turns take 210,000 input tokens ≈ $0.49 plus the same ≈ $0.12 of output — about $0.61 in total. The cache saves ≈ $0.37, around 60%, and the longer the session, the bigger the share of context the cache carries: the constant part is paid for once and read on every turn.