Prompt Caching with Claude API: Cut Costs on Repeated Contexts

Prompt caching with the Claude API became generally available in December 2024, offering up to 90% cost reduction and 85% latency improvement on long repeated contexts. Those numbers are real, but they reflect performance under exactly the conditions the feature was built for, which is not the same as the conditions most teams are in when they first reach for it. The write penalty is where things get complicated, and understanding it before you instrument your code will save you from paying more than standard pricing while thinking you're saving money.

The Basic Mechanics Are Simpler Than the Tradeoffs

When you send a request to the Claude API with cache_control breakpoints, the system checks whether the prompt prefix up to that breakpoint already exists in cache from a recent call. If it does, that portion is served at 10% of the base input token price. If it doesn't, the system writes to cache at 125% of the base input token price, that is, the standard cost plus a 25% surcharge.

The cache TTL defaults to 5 minutes and refreshes on each use within that window, with a 1-hour option available. Cache entries are isolated between organizations and, on the Claude API and Microsoft Foundry, between workspaces within an organization. Anthropic does not store raw prompt text at rest; only key-value cache representations and cryptographic hashes are held in memory. That's the security model, and it's worth knowing if your organization has data governance concerns about what gets cached.

The syntax itself is minimal. You add a cache_control block to the message or system prompt content you want to cache:

{
  "type": "text",
  "text": "[your long static context here]",
  "cache_control": {"type": "ephemeral"}
}

Anthropic's documentation also covers automatic caching on newer models, which handles cache breakpoints without explicit markup. Explicit caching gives you control over exactly where the cache boundary sits, which matters more than it sounds once you understand how the write penalty accumulates.

The 100K-token example documented by Spring.io is the clearest illustration of the ceiling: a request that took 11.5 seconds dropped to 2.4 seconds with caching enabled. At that scale, the economics are obvious and the break-even point arrives almost immediately. At smaller context sizes, the calculation is less favorable and more sensitive to how often the cache actually gets hit.

The Write Penalty Creates a Break-Even Problem Most Teams Don't Calculate Upfront

Here's the scenario that doesn't make it into most tutorials. A marketing automation team is running an A/B test on system prompt variations for a Claude-powered content pipeline. They have five prompt variants, each around 8,000 tokens, and they're calling the API roughly 30 times per variant during the testing phase to evaluate output quality. Every call to a new or modified variant writes to cache. Every write costs 125% of standard input pricing. If the hit rate during active iteration is low because the prompt is changing frequently, the team is paying the write premium on most calls while receiving almost no cache read discounts to offset it.

The math flips from savings to surcharge. Prompt caching's advertised economics assume a stable prompt serving many requests, not a prompt that changes on each test iteration. This isn't a hidden gotcha; Anthropic's own documentation frames caching around "frequently used context between API calls," which implies reuse, not experimentation. The implication is easy to miss when you're instrumenting caching at the same time you're still designing what to cache.

A 2026 arXiv study evaluating caching strategies across 500 agent sessions found that caching reduced API costs 41-80% and improved time-to-first-token 13-31%, but also found that naive full-context caching can paradoxically increase latency. According to that paper, strategic control of the cache boundary outperforms caching everything by default, and that conclusion applies to cost as much as latency. Caching everything means writing everything to cache, which means paying the write premium on content that may never be reused at a rate that justifies it.

Break-even depends on your hit rate, not just your token volume. If you're writing to cache on every call and hitting it on fewer than roughly 80% of subsequent calls (the exact threshold varies by token count and model pricing), you may be running at a net loss relative to standard input pricing. Teams in early-stage deployment, running experiments, or operating with short-lived sessions are structurally disadvantaged by this model.

Prompt Freezing Is a Workflow Constraint, Not a Technical Setting

Real discipline that makes prompt caching pay off is prompt freezing: treating cached content as production-frozen and routing all iteration to a separate, non-cached testing environment. This sounds obvious once stated, but it cuts against how most teams actually work, where the system prompt is a living document that gets tweaked between deploys, sometimes multiple times per day.

A reasonable operational pattern splits the workflow into two distinct phases. During the experimentation phase, caching is disabled entirely. You're paying standard input pricing, your iteration speed is unimpaired by cache write costs, and you're not accumulating write penalties on prompts that won't survive the week. Once a prompt variant is selected and frozen, it moves to the production environment with caching enabled, where it will serve high volume with stable content and generate genuine savings.

Placement of the cache_control breakpoint follows from this logic. Caching should sit at the boundary between your stable context (system instructions, background documents, few-shot examples) and your dynamic content (user messages, session variables, tool results). The arXiv paper's finding that excluding dynamic tool results from cache boundaries outperforms full-context caching reflects exactly this principle: dynamic content doesn't benefit from caching and dilutes the efficiency of what you're caching by forcing more frequent cache writes.

For systems with document-heavy RAG pipelines, the economics are more favorable by default because the retrieved documents are often large, stable within a session, and reused across multiple turns. A 50,000-token document context cached at the start of a session and referenced across 20 turns generates the kind of hit rate that makes the write penalty irrelevant. That's the use case prompt caching was clearly optimized for, and it shows.

From My Experience

In my work managing catalog automation and email personalization pipelines for an e-commerce operation, the pattern that maps most cleanly to this is large, relatively static data payloads that need to be referenced across many successive calls. Product catalogs, taxonomy documents, attribute mapping tables, they're large, they change on a predictable schedule rather than per-call, and they're referenced repeatedly within a session or workflow run. That's the profile prompt caching rewards. A/B testing email subject line generation with varied instruction sets is the counter-case worth flagging for anyone in similar work: the prompts are short, they change constantly, and the per-call volume per variant is low. Caching there would hurt more than help, and it's worth separating that from the document-grounding use cases where the feature genuinely earns its keep.

FAQ

Does prompt caching work across different user sessions, or only within a single session?

Cache entries persist for up to 5 minutes by default (1 hour with the extended TTL option) and are accessible to any request from the same organization or workspace that sends the same cached prefix within that window. They are not session-scoped, so a system prompt cached by one user's request can serve cache hits for another user's request in the same organization, provided the prefix matches. The details are in Anthropic's caching documentation.

Which Claude models support prompt caching?

According to Anthropic's current documentation, both automatic and explicit prompt caching are supported on all active Claude models, including Claude 3.5 Sonnet, Claude 3.5 Haiku, and the Claude 3 family. The pricing ratios (10% for cache reads, 125% for cache writes) apply consistently, though the base input token prices vary by model.

Can I cache tool definitions and few-shot examples, not just system prompts?

Yes. The cache_control breakpoint can be placed on any content block, including tool definitions and example exchanges in the messages array. Caching few-shot examples is one of the more effective use cases when those examples are stable and the volume of calls justifies the write cost. The constraint is that the cached prefix must match exactly, so any change to the content before the breakpoint invalidates the cache entry.

Prompt caching was designed around a specific bet on what production AI systems look like at scale: stable contexts, high call volume, and predictable reuse patterns. When your system matches that profile, the savings arrive quickly and compound across every call. When it doesn't, the write penalty is the cost of learning that lesson.