Claude API Prompt Caching: Cut Costs by 90%

Introduction

If you are building with the Claude API and not using prompt caching, you are almost certainly overpaying. Prompt caching is one of the most impactful yet underused features in the Anthropic developer toolkit. It allows you to reuse previously processed prompt prefixes across requests, cutting input token costs by up to 90% and reducing latency by as much as 85%.

With the recent surge in Claude usage and Anthropic tightening rate limits during peak hours, cost optimization has never been more relevant. Whether you are running a production chatbot, an agentic workflow, or a RAG pipeline, prompt caching can dramatically change your cost structure. This guide covers everything you need to know: how caching works under the hood, the two implementation methods, pricing math, best practices, common pitfalls, and real-world optimization strategies.

How Prompt Caching Works Under the Hood

At its core, prompt caching works by storing processed prompt prefixes so they can be reused in subsequent requests. When you send a request to the Claude API, the system performs a three-step check.

First, it examines whether a prompt prefix up to a designated cache breakpoint already exists in the cache from a recent query. If a match is found, the cached version is used directly, which saves both processing time and token costs. If no match exists, the system processes the full prompt normally, then caches the prefix once the response begins generating.

The critical detail here is that caching operates on a strict prefix-matching basis. The system looks at the content from the beginning of your prompt up to the cache breakpoint. If even a single character changes in the cached prefix, the cache is invalidated and a new entry is written. This is why the order of your prompt components matters enormously.

Claude processes prompt components in a fixed hierarchy: tools come first, then system messages, then the messages array. Changes at any level invalidate the cache for that level and everything after it. If you modify a tool definition, for example, the entire cache is invalidated. But if you only change something in the messages array, your cached tools and system prompt remain valid.

Two Ways to Implement Caching

Anthropic offers two approaches to prompt caching, each suited to different use cases.

Automatic Caching

Automatic caching is the simplest path. You add a single cache_control field at the top level of your API request, and the system handles everything else. The breakpoint automatically moves to the last cacheable block in your prompt and shifts forward as conversations grow.

This approach shines in multi-turn conversations. As the chat history grows, previously processed turns are read from cache while only new content is written. You do not need to manage breakpoint positions manually, which removes a significant source of implementation bugs.

Automatic caching is ideal when your prompt structure is straightforward, when you are building conversational applications, or when you want to get started quickly without optimizing every detail.

Explicit Cache Breakpoints

Explicit breakpoints give you fine-grained control. You place cache_control markers directly on individual content blocks within your prompt, up to a maximum of four breakpoints per request.

This method is powerful when different parts of your prompt change at different frequencies. For example, your tool definitions might stay the same for weeks, your system instructions might change daily, and your RAG context might differ per request. With explicit breakpoints, you can cache each layer independently, maximizing cache hits across the board.

The tradeoff is complexity. You need to understand exactly how the cache hierarchy works and carefully position your breakpoints to avoid common mistakes like placing a breakpoint on content that changes every request.

Pricing: The Math That Makes It Worth It

Prompt caching involves three pricing tiers that you need to understand.

The first is the cache write cost. When content is cached for the first time with the default five-minute TTL, you pay 1.25 times the base input token price. For a one-hour TTL cache, the write cost is 2 times the base price. This is a small premium you pay once to store the content.

The second is the cache read cost. This is where the savings happen. Reading from cache costs just 0.1 times the base input token price, which means a 90% discount on every subsequent request that hits the cache.

The third is the standard input cost. Tokens that appear after your last cache breakpoint are charged at the normal input rate.

Let us look at concrete numbers for Claude Sonnet 4.6, which is the most commonly used model for production workloads. The base input price is 3 dollars per million tokens. A cache write costs 3.75 dollars per million tokens with the default TTL. A cache read costs just 0.30 dollars per million tokens. So if your system prompt is 5,000 tokens and you make 1,000 requests per day, here is the comparison.

Without caching, you pay 5,000 tokens multiplied by 1,000 requests at the base rate, totaling 15 dollars per day just for the system prompt. With caching, you pay one cache write of 5,000 tokens at 3.75 dollars per million plus 999 cache reads at 0.30 dollars per million. That comes out to roughly 1.52 dollars per day. The savings are over 13 dollars daily, or more than 400 dollars per month, from a single optimization.

For Claude Opus 4.6 users, the savings are even more dramatic because the base input price is higher at 5 dollars per million tokens while cache reads are only 0.50 dollars per million.

Minimum Token Requirements You Must Know

Not every prompt can be cached. Anthropic enforces minimum cacheable lengths that vary by model, and these have changed with newer model releases.

Claude Opus 4.6 and Claude Haiku 4.5 require a minimum of 4,096 tokens in the cached prefix. Claude Sonnet 4.6 requires 2,048 tokens. Claude Sonnet 4.5 and Claude Sonnet 4 require only 1,024 tokens.

If your prompt prefix falls below the minimum threshold, the API will not return an error. Instead, it silently processes the request without caching. This is a common source of confusion for developers who set up caching and wonder why their usage reports show zero cache hits. Always check the cache_creation_input_tokens and cache_read_input_tokens fields in the API response to verify that caching is actually working.

If your system prompt alone is too short to meet the threshold, consider combining it with tool definitions or static context documents to reach the minimum. The key is that the total prefix length up to the breakpoint must meet the requirement.

Cache TTL: Choosing Between 5 Minutes and 1 Hour

By default, cached content lives for five minutes. Every time the cache is accessed within that window, the TTL resets at no additional cost. This works well for high-frequency use cases where requests come in every few seconds or minutes.

But what about scenarios where requests are less frequent? Anthropic introduced a one-hour cache TTL option for exactly this purpose. You activate it by adding a ttl field set to \"1h\" inside your cache_control parameter.

The one-hour cache costs twice the base input price to write, compared to 1.25 times for the five-minute cache. However, the read price remains the same at 0.1 times the base price. So the question becomes whether the extra write cost is offset by the additional cache hits you gain from the longer window.

Use the one-hour TTL when your application has gaps between requests that exceed five minutes but are shorter than an hour. This is common in user-facing chatbots where someone might take a ten-minute break between messages, in agentic workflows where Claude executes multi-step tasks that take more than five minutes, or in batch processing scenarios where you process items with variable delays between them.

You can also mix TTLs within a single request. Place longer-TTL breakpoints before shorter-TTL ones. The API automatically handles the cost calculation, applying the appropriate write cost to each segment based on its TTL.

Best Practices for Maximum Savings

After working with prompt caching extensively, several patterns consistently deliver the best results.

Structure your prompts with stability in mind

Place content that changes least frequently at the beginning of your prompt. Tool definitions should come first since they rarely change. System instructions should follow. Dynamic context like RAG documents or user-specific data should come next. The current conversation or user message should always be last.

This ordering maximizes the prefix that remains identical across requests. Even if your RAG context changes, your cached tools and system prompt still generate cache hits.

Place breakpoints on the last stable block

The most common mistake developers make is placing a cache breakpoint on content that changes every request. If you have a timestamp, a request ID, or any per-request dynamic content in a block, do not put a breakpoint on it. The breakpoint should go on the last block that remains identical across requests.

Monitor your cache hit rates

Every API response includes usage fields that tell you exactly what happened with caching. The cache_read_input_tokens field shows tokens that were read from cache. The cache_creation_input_tokens field shows tokens that were written to cache. The input_tokens field shows tokens processed after the last breakpoint.

Your total input token count is the sum of all three. If cache_read_input_tokens is consistently zero, something is wrong with your caching setup. Log these values and track your cache hit rate over time.

Use automatic caching for conversations, explicit for complex pipelines

Do not over-engineer your caching setup. For straightforward multi-turn conversations, automatic caching handles everything correctly. Reserve explicit breakpoints for complex scenarios where different prompt sections have different update frequencies.

Combine caching with batch processing

For non-real-time workloads, Anthropic offers a Batch API that provides a 50% discount on token costs. Combining prompt caching with batch processing can reduce costs by up to 95% compared to uncached real-time requests. This is the gold standard for bulk data processing tasks.

Common Pitfalls and How to Avoid Them

The silent failure trap

Prompt caching never throws errors. If your content is too short, if your breakpoint is on changing content, or if your cache has expired, the API simply processes the request normally at full price. Always validate caching through usage metrics, not through the absence of errors.

Key ordering in tool definitions

Some programming languages do not guarantee consistent JSON key ordering in dictionaries or maps. If your tool definitions serialize with different key orders across requests, the cache sees them as different content and never hits. This has been specifically reported as an issue in Swift and Go. Ensure your serialization produces deterministic output.

Invalidation from feature toggles

Enabling or disabling certain API features can modify your prompt in ways that invalidate the cache. Toggling web search modifies the system prompt internally. Toggling citations does the same. Changing the speed setting between fast and standard also affects caching. If you are seeing unexpected cache misses, check whether any feature flags are changing between requests.

The 20-block lookback limit

When using explicit breakpoints, the system looks backward through a maximum of 20 content blocks to find a cache hit. If your conversation history grows beyond 20 blocks between breakpoints, add an additional breakpoint closer to the current position to ensure the cache can still be found.

Caching with Extended Thinking

If you use Claude's extended thinking feature, there are special behaviors to understand. Thinking blocks are cached automatically as part of the request content without needing explicit cache markers. In fact, you cannot place a cache_control marker directly on a thinking block.

The important nuance is how thinking blocks interact with conversation flow. When a user sends a non-tool-result message, all previous thinking blocks in the conversation are stripped. This means the cache entry changes. However, when tool results are added to continue an agentic loop, thinking blocks are preserved and the cache remains valid.

For agentic workflows that involve multiple tool calls, this means the cache naturally extends through the tool-use loop. But once the human responds, the cache for thinking content is invalidated. Keep this in mind when estimating cost savings for extended thinking use cases.

Workspace Isolation: A Recent Change

As of February 2026, Anthropic moved cache isolation from organization-level to workspace-level. This means that caches are no longer shared between different workspaces within the same organization.

If your team uses multiple workspaces for different projects or environments, this change means each workspace maintains its own cache. Requests in workspace A will not benefit from caches created in workspace B, even if the prompts are identical. Review your workspace structure to ensure related workloads that share prompt prefixes are in the same workspace.

Real-World Impact: When Caching Pays for Itself

Prompt caching delivers the highest ROI in specific scenarios.

Production chatbots with consistent system prompts see immediate benefits because every conversation reuses the same instruction prefix. A system prompt of 3,000 to 5,000 tokens across thousands of daily conversations translates to hundreds of dollars in monthly savings.

RAG applications that query against large document collections benefit enormously. You can cache the document context and only pay full price for the user's query tokens.

Agentic workflows where Claude calls tools in multi-step loops accumulate significant savings because each step in the loop reuses the cached prompt prefix from prior steps.

Code review and analysis tools that process files against consistent rule sets can cache the rules and coding standards, paying cache read rates for every file reviewed.

The common thread is repetition. Any time the same prompt prefix appears in multiple requests within your cache TTL window, caching pays for itself.

Conclusion

Prompt caching is not an advanced optimization technique reserved for large-scale deployments. It is a fundamental cost management tool that every Claude API developer should implement from day one. The combination of 90% cost reduction on cached tokens, significant latency improvements, and straightforward implementation makes it one of the highest-impact changes you can make to your Claude integration.

Start with automatic caching for your multi-turn conversations. Graduate to explicit breakpoints as you gain confidence and your prompt architecture becomes more sophisticated. Monitor your cache hit rates religiously, and do not forget to combine caching with batch processing for offline workloads.

With Anthropic continuing to invest in model capabilities and the Claude user base growing rapidly, managing your API costs effectively is essential for building sustainable applications. If you are tracking your Claude usage patterns to identify optimization opportunities, tools like SuperClaude can help you monitor consumption across models and spot where prompt caching would deliver the biggest savings.