Claude Prompt Caching: How It Works, Costs, 512-Token Minimum

Claude prompt caching lets the API reuse the beginning of a request it has already processed. You mark a point in the request with cache_control, Claude stores everything before that point in the order tools, system, messages, and the next request that starts with exactly the same content reads that prefix at a fraction of the input price instead of paying for it again. A cached prefix lives for 5 minutes by default and every hit restarts the clock; a 1-hour lifetime is available at a higher write price. As of October 30, 2026, Anthropic's prompt caching documentation lists caching on all active Claude models.

To switch it on, add "cache_control": {"type": "ephemeral"} at the top level of your Messages API request, or on the last block that stays identical between calls, and make sure the cached part is at least 512 tokens. That is the minimum on Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1 and Opus 5; Sonnet 5 needs 1,024 tokens, and older models need 1,024, 2,048 or 4,096 (Sonnet 4.6, Opus 4.7 and Haiku 4.5 respectively). Then send the same prefix again and look for a non-zero cache_read_input_tokens in the response. In a test on October 30, 2026, a 7,882-token system prompt sent to Sonnet 5.5 through LaoZhang's Anthropic-format endpoint was written to the cache on the first call and read in full on the next two.

The price side has changed too. Reads are no longer a flat 10% of input: they cost 0.05x on Opus 5.5 and Sonnet 5.5, 0.025x on Fable 5.1 and 0.1x on Haiku 5.5, while writes cost 1.25x for 5 minutes or 2x for 1 hour. Caching therefore costs more than not caching when a prefix is used only once or your calls are spaced further apart than its lifetime. If you only use Claude Code, you don't need to set anything: it caches automatically, with a 1-hour lifetime for the main conversation on a Claude subscription and 5 minutes on an API key, as explained in Claude Code Cache TTL and Token Usage: Why Cache Misses Get Expensive and How to Prove It.

What Claude caches: the prefix up to your cache_control marker

Claude caches a prefix, not an answer and not a single block. The cache key is the whole request in a fixed order, tools, then system, then messages, up to and including the block that carries cache_control. A later request gets a hit only when every byte up to that point is identical: the same tool definitions in the same order, the same system text, the same earlier turns and images. Change one character in the system prompt and everything after it, including a long conversation history that was already cached, has to be written again. That is the whole design rule for a cache-friendly request: stable content first, and anything that changes per request (a timestamp, a user ID, retrieved snippets, the new question) after the marker.

Timing follows the same documentation. The entry is created once the response starts, so a second request sent in parallel with the first can't read it yet. Its 5-minute lifetime is measured from the start of the request that wrote or last read it, not from the end of the response, so a streamed answer that takes 4 minutes leaves roughly 1 minute of cache life. Each hit refreshes the lifetime at no extra cost.

A cache is also narrower in scope than one shared pool. Caches are never shared between organizations, and on the Claude API they are isolated per workspace; on Amazon Bedrock and Google Cloud the boundary is the organization. Each model also keeps its own cache: in the October 30 test, the same 7,882-token prefix already cached on Sonnet 5.5 was written from scratch when it was sent to Opus 5.5, and only the second Opus call read it.

You can cache tool definitions, system blocks, text in user and assistant turns, images and documents in user turns, and tool_use and tool_result blocks. Thinking blocks can't carry a marker themselves; they get cached along with the earlier assistant turn they belong to and count as input tokens when read back. Citation sub-blocks and empty text blocks can't be cached either, so for citations you cache the source document instead.

Turn it on: automatic caching or an explicit cache_control breakpoint

Use automatic caching for a chat or agent loop whose history only grows, and an explicit breakpoint when a stable block is followed by something that changes on every request. Both use the same prices, the same per-model minimum (512 tokens on the 5.5 models) and the same 20-block lookback, and you can combine them. Anthropic's own advice is to start with automatic caching for multi-turn conversations.

Automatic caching: one top-level field

Put a single cache_control object at the top level of the request body. Claude places the breakpoint on the last cacheable block and moves it forward as the conversation grows, so each request reads what the previous one wrote and writes only the new tail.

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are a support assistant for Acme. Use the handbook below. ...full handbook text, 512+ tokens...",
    "messages": [
      {"role": "user", "content": "How do I reset a customer password?"}
    ]
  }'

In a Python loop, keep the history append-only and send assistant content back exactly as you received it, because a re-serialized earlier turn breaks the prefix:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
SYSTEM = open("handbook.md").read()  # the stable part, 512+ tokens
history = []

def ask(question: str):
    history.append({"role": "user", "content": question})
    resp = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system=SYSTEM,
        messages=history,
    )
    history.append({"role": "assistant", "content": resp.content})
    u = resp.usage
    print("write", u.cache_creation_input_tokens, "read", u.cache_read_input_tokens, "uncached", u.input_tokens)
    return resp

In the October 30 test, a three-turn automatic-caching conversation on Sonnet 5.5 behaved exactly like that: turn 1 wrote 7,906 tokens, turn 2 read those 7,906 and wrote 65 new ones, and turn 3 read 7,971 and wrote 74. Three edge cases return errors instead of caching: four explicit breakpoints already in the request (no slot left), an explicit marker on the last block with a different TTL, and the legacy Amazon Bedrock integration for Opus 4.6 and earlier, which rejects a top-level cache_control with a 400.

Explicit breakpoint: mark the last block that stays the same

Automatic caching puts the breakpoint on the last block, which is wrong for a single-turn request whose final block is a new question every time: Claude writes the system prompt plus that question, the next question produces a different prefix, and nothing is ever read. Writes happen only at breakpoints, and the lookback searches only for entries that earlier requests wrote, so it won't discover the stable system prompt behind a changing block. Put cache_control on the stable block yourself:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Answer questions about the contract below. ...full contract text, 512+ tokens...",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "Current time: 2026-10-30 09:00 UTC. What is the notice period?"}
    ]
  }'

This is the layout used in the October 30 test: a breakpoint on a 7,882-token system block, then three different questions to Sonnet 5.5. The first call reported cache_creation_input_tokens: 7882 with 28 uncached input tokens, and the next two reported cache_read_input_tokens: 7882 with no write. For a 1-hour lifetime, write the marker as {"type": "ephemeral", "ttl": "1h"}.

A request can carry up to four breakpoints, and the markers themselves cost nothing. A common split is one on the tool definitions or system prompt and a top-level automatic marker for the conversation. If you mix lifetimes, 1-hour entries have to come before 5-minute ones. In long agent loops, watch the 20-block lookback: if one turn adds 20 or more blocks after the last write, the next request can't find that entry, so add a second breakpoint earlier in the conversation before you need it. On the Claude API a run of consecutive tool_use blocks counts as one position, as does a run of tool_result blocks.

What caching costs per model: writes 1.25x–2x, reads 0.025x–0.1x

Cache writes cost more than normal input and cache reads cost far less. A 5-minute write is 1.25x the model's base input price and a 1-hour write is 2x; a read is 0.1x on most models but 0.05x on Opus 5.5 and Sonnet 5.5 and 0.025x on Fable 5.1. Output tokens are priced the same with or without caching. These are Anthropic's list prices per million tokens in USD, from the Claude prompt caching pricing table as of October 30, 2026:

The ratio between a write and a read is what makes a miss expensive. On Opus 5.5 and Sonnet 5.5 a 5-minute write costs 25 times a read (1.25 ÷ 0.05), on Haiku 5.5 12.5 times and on Fable 5.1 50 times, so the "reads cost 10%" rule of thumb now fits only Haiku 5.5 and older models. Sonnet 5.5 got its lower read price on October 7, 2026; what that change does to an existing bill is worked out in Claude Sonnet 5.5 Cache Read Price Cut to $0.10: What You Save. The full rate cards are in Claude Fable 5.1 API Pricing: What Changed and What You'll Pay and Claude Opus 5.5 Pricing and Limit Reset: What Each One Changes.

Haiku 5.5 has one trap. Its price depends on prompt length, and cached reads and writes count toward that length, so a 90,000-token cached prefix plus a 15,000-token question makes a 105,000-token prompt and the whole request moves to the over-100K rates in the table. The cache multipliers also stack with the Batch discount, long-context pricing and data residency pricing. If you are still choosing between the two smaller models, Claude Haiku 5.5 vs Sonnet 5.5: When the 20x Price Gap Pays Off compares them by cost per task.

To see what this does to a real workload, take an 80,000-token prefix sent 20 times inside its lifetime. Without caching you pay 20 × 80,000 input tokens. With caching you pay one write and 19 reads. Input side only, at the list prices above:

For Sonnet 5.5 the 5-minute line is 80,000 × $2.50/M for the write ($0.20) plus 19 × 80,000 × $0.10/M for the reads ($0.152). Smaller prefixes save less in dollars but a similar share: the 7,882-token test prompt sent 10 times on Sonnet 5.5 costs $0.1576 uncached, $0.0268 with the 5-minute cache and $0.0386 with the 1-hour cache.

5 minutes or 1 hour: when caching pays off and when it costs more

If the same prefix comes back at least once every 5 minutes, keep the default. Each hit refreshes the 5-minute entry for free, and the cache is already cheaper than no cache on the second call on every current model: on Opus 5.5 or Sonnet 5.5, two calls cost 1.25 + 0.05 = 1.30 units of base input instead of 2.00 (Haiku 5.5: 1.35; Fable 5.1: 1.275). The 1-hour cache needs a third call to pay off, because two calls cost 2 + 0.05 = 2.05 units, slightly more than the 2.00 you'd pay uncached, while three cost 2.10 against 3.00. Choose 1 hour when the gaps fall between 5 and 60 minutes, such as a user who reads a long answer before replying or a sub-agent that runs longer than 5 minutes; Anthropic says both lifetimes give the same latency benefit.

Caching costs more than no caching in three situations. A prefix used only once pays the 1.25x or 2x write and is never read back. A 5-minute cache on traffic that arrives every 10 minutes expires before each call, so you pay the write premium every time: for a 100,000-token prefix on Sonnet 5.5 and six calls an hour, that is $1.50 an hour against $1.20 with no cache at all (25% more), while a 1-hour cache costs $0.40 for the write plus 5 × $0.01 for the reads, $0.45 in total. The third case, several cold requests sent in parallel, is covered in the checklist below.

The lifetimes behaved as documented in the October 30 test on Sonnet 5.5. A 5-minute entry written at 04:45:11 UTC was read 6 seconds later, then written from scratch after 6 minutes 20 seconds of idle time. A 1-hour entry written at 04:46:21 UTC was still read at 04:53:34, after 7 minutes idle. Each was a single gap length, so the exact expiry point and the 1-hour upper bound weren't measured.

Prove a cache hit from the usage fields

Every Messages API response tells you what the cache did in its usage object. A non-zero cache_creation_input_tokens means this call wrote the prefix and paid the write rate, a non-zero cache_read_input_tokens means it read the prefix, and both at zero mean nothing was cached at all, usually because there was no marker or the prefix was under the minimum. input_tokens counts only the tokens after the last breakpoint, so total input is read + creation + input_tokens. With streaming, these fields arrive in the message_start event.

The quickest health number is a hit rate: cache_read_input_tokens ÷ (cache_read_input_tokens + cache_creation_input_tokens + input_tokens). In the three-turn automatic test, turn 3 read 7,971 of its 8,049 input tokens (7,971 + 74 written + 4 uncached), a hit rate of about 99%. A rate that stays near zero on repeat calls means something in the prefix is changing between them.

Cache miss checklist: why Claude wrote the prefix again

When a repeat call still shows a write and no read, one of the causes below is almost always responsible. Check them in this order, because the first few need nothing more than the usage object and a look at your request body.

The October 30 tests on Sonnet 5.5 reproduced several of these rows. Prefixes of 180 and 377 tokens with a marker returned both cache fields at 0 with HTTP 200 and no warning, while 567- and 1,094-token prefixes cached normally, so a silent zero is the only sign you'll get. Three identical cold requests sent at once each wrote all 7,882 tokens, which cost $0.0591 instead of the $0.0213 that one write and two reads would have cost. Switching effort from low to medium and back kept the system-prompt cache, consistent with the Claude Code documentation's note that effort changes keep the cache on the 5.5 models. Anthropic's API documentation adds that an effort change always invalidates the cached message blocks, and that part wasn't isolated in the test.

Ask the Claude API where the prefix changed

On the Claude API you don't have to guess: cache diagnostics compares two consecutive requests and reports where they first differ. Add "diagnostics": {"previous_message_id": null} to the first request and the previous response's id to each later one. The response then carries a diagnostics object whose cache_miss_reason.type is model_changed, system_changed, tools_changed or messages_changed, with cache_missed_input_tokens as a rough size of what was lost; diagnostics: null means no divergence. A type of previous_message_not_found or unavailable means no comparison was made, which is not proof that your request changed. Per Anthropic's cache diagnostics documentation, it works on Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 and other listed models, no longer needs a beta header, and is available on the Claude API only.

"diagnostics": {"previous_message_id": "msg_..."}

Does caching work through a gateway or the OpenAI-compatible endpoint?

Caching can work through a gateway, but the gateway decides what reaches Anthropic and which fields come back, so confirm it with usage on your own traffic rather than assuming it. All 51 test calls on October 30, 2026 went through LaoZhang's Anthropic-format endpoint, https://api.laozhang.ai/v1/messages, with Authorization: Bearer $LAOZHANG_API_KEY and anthropic-version: 2023-06-01 (in the Anthropic SDK, set base_url="https://api.laozhang.ai"). Explicit breakpoints, automatic caching and the 1-hour TTL all worked as Anthropic documents them. LaoZhang's documentation lists 5-minute and 1-hour caching for its Claude models, and its listed input, output and cache-read prices for Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 equal Anthropic's.

Disclosure: laozhang.ai is our own service. Its prices are platform pricing, not an independent comparison.

Some results through this gateway are not what Anthropic documents, and they shouldn't be read as Claude API behavior, because the direct API wasn't tested. Requests with no cache_control anywhere still had the 7,882-token system prompt written on the first call and read on the second. A breakpoint placed on a user block containing a fresh timestamp, which Anthropic says produces a write every time and never a read, still read the 7,882-token system part and wrote only 31–48 new tokens per call. The likely explanation is that the gateway or the upstream service behind it marks the system prompt for caching on its own.

That has a billing consequence worth knowing. A first call without cache_control was charged 1.9788 cents, which is 7,882 × $2.50/M for a 5-minute write plus 11 input tokens at $2/M and 6 output tokens at $10/M; the same call uncached would have cost 1.5846 cents, so the first call cost 25% more than it would have without caching. The repeat call was charged 0.0872 cents. So through this gateway, a one-off request with a long system prompt pays the write premium even if you never asked for caching, and repeated ones get cheaper. Across all 51 calls the account was charged $0.471, against $0.469 recomputed from the logged usage at list prices, so the write and read rates applied were the official ones. Three other differences: the 1-hour responses had no cache_creation breakdown object, the diagnostics object returned nothing, and max_tokens: 0 did not behave as a pre-warm (next section).

The OpenAI-compatible endpoint, POST /v1/chat/completions with claude-sonnet-5-5, also cached the system message without any cache fields in the request. It reported the write as prompt_tokens_details.cached_creation_tokens: 7882 on the first call and the read as prompt_tokens_details.cached_tokens: 7882 on the second. In that format prompt_tokens (7,893) already includes the cached tokens, unlike Anthropic's input_tokens, so don't add the two together when you calculate cost. With any other gateway or proxy, the first thing to check is whether it forwards cache_control unchanged; one that strips it silently bills the whole prompt as uncached input.

Warm the cache before users arrive with max_tokens: 0

On the Claude API, you can write the cache ahead of real traffic by sending the shared prefix with max_tokens: 0. The API writes the entry at the breakpoint, returns empty content with stop_reason: "max_tokens" and bills no output tokens. Put the explicit breakpoint on the last block the real requests will share (usually the system prompt or tools), not on the placeholder user message, and use the same thinking and effort settings as the follow-up calls. Automatic caching doesn't suit this, since it would place the breakpoint on the placeholder.

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 0,
  "output_config": {"effort": "low"},
  "system": [
    {"type": "text", "text": "...the shared system prompt...", "cache_control": {"type": "ephemeral"}}
  ],
  "messages": [{"role": "user", "content": "warmup"}]
}

Anthropic rejects a max_tokens: 0 pre-warm with stream: true, with thinking set to enabled, with structured outputs, with tool_choice set to tool or any, and inside Message Batches, and it now prefers this method over the older max_tokens: 1 workaround. Through LaoZhang on October 30, 2026, however, max_tokens: 0 produced a normal 46-token reply along with the 7,882-token write, so the gateway appears to treat 0 as unset; max_tokens: 1 returned a single output token, wrote the prefix, and the follow-up call read it. A warm-up is a paid write, so it only pays off if real requests arrive inside the lifetime. It also solves the parallel cold start: warm once, wait for that response to begin, then send the burst.

Claude prompt caching: other questions

Is prompt caching on by default in the Claude API?

No. On the Messages API, nothing is cached unless the request carries cache_control, either at the top level or on a block, according to Anthropic's documentation as of October 30, 2026. Claude Code and Claude Managed Agents cache automatically, and some gateways add caching of the system prompt on their own, which shows up as a non-zero cache_creation_input_tokens on requests you didn't mark.

Do cache hits count against Claude API rate limits?

Anthropic's prompt caching documentation states that cache hits are not deducted against your rate limit, and lists better rate-limit use as one reason to choose the 1-hour cache. If you are hitting 429 errors anyway, Claude API Error: Rate Limit Reached: Find the Right Limit Before You Retry explains which limit a given error belongs to.

Does prompt caching change Claude's answers?

No. Anthropic states that caching has no effect on the output; a cached request produces the same kind of response the uncached request would. What changes is the input price and, for long prompts, the time to first token.