Skip to main content

Prompt Caching

Claude bills cached input tokens at a fraction of base price, but the cache is a strict prefix match: one changed byte invalidates everything after it.

Hand-drawn ink-line illustration on terracotta: two loopy hands square a stack of cream sheets flush at the left edge while one sheet juts out of line, a one-line profile face observing.

The one rule​

Anthropic's post Lessons from building Claude Code: prompt caching is everything (April 2026) states it as bluntly as documentation gets: "Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it. Design your entire system around this constraint." The same post notes the team runs alerts on its own cache hit rate and declares SEVs when it drops. That is caching treated as architecture, not as an optimization pass.

The design consequence is an ordering discipline: stable content first. The request renders as tools, then system, then messages, per the prompt caching docs, so tool definitions and the system prompt should be frozen, and anything volatile (timestamps, request IDs, per-user detail) belongs after the last cache breakpoint. A "helpful" dynamic date string at the top of a system prompt silently zeroes the cache on every request behind it.

The economics​

Per the platform docs (verify against platform.claude.com/docs; pricing and TTLs drift): cache reads cost roughly 0.1x base input price. Cache writes cost 1.25x base for the 5-minute TTL or 2x for the 1-hour TTL, which puts break-even at the second request on the short TTL. For agents, whose loops resend a growing conversation on every model call, this is the difference between linear and quadratic-feeling input bills.

Verification is one field: usage.cache_read_input_tokens in the response. If it reads zero across requests that should share a prefix, something in the prefix is churning, and the bill is quietly paying full price.

The published numbers​

Caching produces some of the hardest cost figures in the entire customer corpus:

  • Notion reports "Reduced costs by 90% and latency by up to 85% with prompt caching." (source)
  • Dust reports "Cache reads doubled from about 30% to 65% of input tokens, input spend fell 22%, and overall model spend fell 18–19%: roughly $10K saved per day." (source)
  • Greptile "Achieves ~90% cache hit rates, dramatically reducing costs for both Greptile and self-hosting customers." (source)
  • Bolt's maker StackBlitz "sees roughly 90% cache efficiency on the Agent SDK, keeping inference costs manageable across these long-running workflows." (source)

Note what the strongest cost stories have in common: they talk about cache hit rates and prompt structure, not about switching to a cheaper model.

Where it comes free​

On Managed Agents, caching on repeated history is applied by the platform, and the Agent SDK's harness caches aggressively by default (the ~90% figures from Greptile and Bolt above are SDK deployments). On the raw Messages API you place cache breakpoints yourself, which is more control and more ways to break it. Either way the prefix rule governs, which is one more argument for a frozen, versioned agent config.

Further Reading​