Anthropic Prompt Caching

Type: official-docs Tier: 1 (Official Doc) URL: https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching Accessed: 2026-06-09 Publisher: Anthropic Link: https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching Related (in repo): sources/official-docs/anthropic-pricing.md (the per-MTok base prices the multipliers below apply to)

What it caches

A stable prompt prefix reused across requests: tool definitions, the system prompt, long documents/context, few-shot examples, and prior conversation turns. You mark the end of the stable region with a cache_control: {"type": "ephemeral"} breakpoint (up to 4 explicit breakpoints; or automatic caching that moves the breakpoint forward as a conversation grows).

The one rule that makes it work

The cached prefix must be identical across requests and come BEFORE the variable content. A breakpoint placed on a block that changes every request (a timestamp, the incoming user message) caches nothing useful. Order: stable content first → breakpoint → variable content last.

Cost mechanics (the reason it's a cost lever)

Multipliers on the model's base input price (anthropic-pricing.md):

| Operation | Cost vs. base input | |-----------|---------------------| | Cache write, 5-min TTL | ~1.25× | | Cache write, 1-hour TTL | ~2× | | Cache read (hit) | ~0.1× | | Uncached input (after breakpoint) | 1× |

So a cache write costs slightly more than a normal call; the savings come from every subsequent read at ~1/10th the input price. Caching only pays off when the prefix is reused enough times to amortize the write — a real engineering tradeoff, not a free win.

TTL

Default 5-minute ephemeral cache (refreshed free on each hit). Optional 1-hour TTL at the higher write multiplier — for prompts reused less than every 5 min, or agentic steps that take longer than 5 min between calls.

Minimums and verification

There is a minimum cacheable prefix length (on the order of ~1k tokens, model-dependent; check the doc for the current number per model). Shorter prefixes silently don't cache. Verify caching actually happened via the response usage: total_input = cache_read_input_tokens + cache_creation_input_tokens + input_tokens.

Why This Source Matters

It is the first, cheapest cost lever: no quality change at all (same model, same output), pure input-cost reduction on a reused prefix. The learner measures cache_read_input_tokens to prove the saving — and learns that caching a variable prefix saves nothing (the common mistake).

Key Claims

• Caching reuses a stable prompt prefix (tool definitions, system prompt, long documents, few-shot examples, prior turns) marked with a cache_control breakpoint.
• The cached prefix must be identical and come before variable content; a breakpoint on per-request content (timestamp, incoming message) caches nothing useful.
• Cost mechanics make it a real tradeoff: cache write ~1.25× (5-min) / ~2× (1-hour) base input, cache read ~0.1×; it pays off only once the prefix is reused enough to amortize the write — verify via usage.cache_read_input_tokens.

Relevant To

• Elective 03 — Cost & Latency Engineering (the prompt-caching lever, M1).
• Related: anthropic-pricing.md (the base per-MTok prices the multipliers apply to). Minimums and exact multipliers are model-specific — read the live doc, don't hardcode.

Known issues / cautions

• Cache writes cost more than uncached input — a prefix reused only once is a net loss.
• Invalidation cascades: changing tools invalidates tools+system+messages; changing the system

prompt invalidates system+messages. A prefix that changes per request never caches.

• Thresholds and exact multipliers are model/platform-specific and change — read the live doc;

don't bake a number into code as if permanent.