Prompt Caching

Prompt caching lets you mark a point in a request after which Claude's API can reuse previously processed content instead of reprocessing it from scratch — cutting cost by up to 90% and latency substantially on any request that repeats a large, unchanging prefix.

The problem: paying full price for the same context, over and over

☺ Like you're 10: It's like re-reading the whole instruction manual from page one every time a friend asks a two-word question, instead of just picking up where you left off.

Once your prompts grow past a "hello world" call, a pattern shows up fast: most of what you send on every request is identical to what you sent last time. A support bot resends its entire product manual as a system prompt on every question. A coding agent resends the same twelve tool definitions on every turn. A document-analysis app resends the same 40-page PDF on every follow-up question about it.

Without caching, the API reprocesses that entire prefix from the first token every single time — you pay full input-token price and full processing latency for content that hasn't changed since the last call. If your system prompt plus tool definitions plus reference document adds up to 20,000 tokens and the actual user question is 15 tokens, you're paying for 20,000 tokens of redundant work on every turn of the conversation.

Prompt caching fixes this by letting the API remember the processed state of a prefix and reuse it on a subsequent request, as long as that prefix is byte-for-byte identical to what was cached.

How cache_control breakpoints work

☺ Like you're 10: It's a bookmark, not a highlighter — everything from the start of the book up to where you stick the bookmark gets remembered; nothing after it does.

You mark a cache breakpoint by adding a cache_control field to a content block: {"type": "ephemeral"}. That marker tells the API "cache everything in this request up through this block." On the next request, if the API finds a prior cache entry whose content matches that same prefix exactly, it reads the cached version instead of reprocessing it — you're billed at a fraction of the normal input price for those tokens, and the response starts faster.

The request body is rendered in a fixed order: tools, then system, then messages. A breakpoint on the last block of your system prompt caches the tool definitions and the system prompt together, since both come before it in render order. You can place up to 4 cache breakpoints in a single request, and each breakpoint looks back at most 20 content blocks to find a matching prior entry — long agentic turns with many tool calls may need an intermediate breakpoint to stay within that lookback window.

The mechanism is a strict prefix match: the cache key is derived from the exact bytes of the prompt up to the breakpoint. Change one character anywhere before a breakpoint — reorder a JSON key, swap a tool, interpolate a timestamp — and every breakpoint at or after that position misses.

What goes before the breakpoint, what stays dynamic

The candidates worth caching are the parts of a prompt that are large and don't change from request to request: long system instructions, a fixed set of tool definitions, a reference document or codebase the model needs on every turn, or a block of few-shot examples. Everything that genuinely varies per request — the user's actual question, retrieved search results, a timestamp — has to stay after the last breakpoint, or it will invalidate the cache on every single call.

The cost and latency tradeoff

☺ Like you're 10: Storing something in memory takes a little extra effort the first time; recalling it later is nearly free. That's the whole trade.

Caching isn't free — writing an entry costs more than a normal input token, because the API has to reprocess and store it. Reading a cache hit is cheap. The economics depend on the TTL (time-to-live) you choose:

In other words: the first request that writes a cache entry costs slightly more than an uncached call. Every request after that, within the TTL, that reads the same prefix costs roughly a tenth of the normal input price for those tokens. For a chat session where the same large system prompt gets reused across dozens of turns, or a batch job that asks a hundred questions about the same document, the savings compound quickly.

There's also a minimum size below which a prefix won't cache at all — no error, it just silently doesn't create an entry (you'll see cache_creation_input_tokens: 0). The minimum sits somewhere in the range of roughly 512–4,096 tokens depending on which model you're calling, with larger/faster models generally tolerating a smaller minimum — check the current per-model minimums on platform.claude.com before relying on an exact number.

Placing cache_control in a request

The marker goes directly on the content block you want the cache boundary to end at — most commonly the last block of your system prompt, or the last tool definition if you want to cache only the tools.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": (
                "You are a support agent for Acme Cloud. Use the product "
                "manual below to answer questions.\n\n" + PRODUCT_MANUAL_TEXT
            ),
            "cache_control": {"type": "ephemeral"},  # cache everything up to here
        }
    ],
    messages=[
        {"role": "user", "content": "How do I rotate an API key?"}
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

# Inspect the usage block to confirm caching is actually happening
print(response.usage.cache_creation_input_tokens)  # tokens written to cache (first call)
print(response.usage.cache_read_input_tokens)      # tokens served from cache (later calls)
print(response.usage.input_tokens)                 # tokens processed at full price

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: `You are a support agent for Acme Cloud. Use the product manual below to answer questions.\n\n${PRODUCT_MANUAL_TEXT}`,
      cache_control: { type: "ephemeral" } // cache everything up to here
    }
  ],
  messages: [
    { role: "user", content: "How do I rotate an API key?" }
  ]
});

for (const block of response.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

console.log(response.usage.cache_creation_input_tokens);
console.log(response.usage.cache_read_input_tokens);
console.log(response.usage.input_tokens);

The same field works on tool definitions. If your tool list is large and stable, mark the last tool instead (or in addition) to cache the tool schemas independently of the system prompt:

"tools": [
  {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": { "type": "object", "properties": { "location": {"type": "string"} }, "required": ["location"] }
  },
  {
    "name": "search_docs",
    "description": "Search the internal knowledge base",
    "input_schema": { "type": "object", "properties": { "query": {"type": "string"} }, "required": ["query"] },
    "cache_control": { "type": "ephemeral" }
  }
]

Run the same request twice with an unchanged prefix and you'll see the shift directly in usage: the first call reports tokens under cache_creation_input_tokens (the write), and the second call reports the same tokens under cache_read_input_tokens (the read) at roughly a tenth of the price.

Gotchas: expiry and invalidation

☺ Like you're 10: It's like your bookmark falling out if you leave the book alone too long, or someone sneaking in and changing a word on page one — either way, you're starting over from the top.