Prompt Caching in Claude: Cutting Your API Bill Without Cutting Quality

Look at a few consecutive requests from your Claude application and compare them. In most agents, the system prompt, the tool definitions and any reference documents are identical from one request to the next, and you pay the full input price for them every time.

Prompt caching lets Claude reuse that repeated beginning of the prompt instead of processing it again.

Benefit 1: Lower input costs

Reading tokens from the cache costs roughly a tenth of the normal input price. Writing to the cache costs about 1.25 times the normal price for the default five-minute lifetime, so you save money as soon as the cached content is reused.

Benefit 2: Faster responses

Cached content doesn't have to be processed again, so the first part of the response arrives sooner. The difference is most noticeable with long documents in the prompt.

Benefit 3: Easy to turn on

The simplest version is a single parameter:

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4000,
    cache_control={"type": "ephemeral"},
    system=LONG_STABLE_INSTRUCTIONS,
    messages=conversation,
)

For more control, you can place cache_control on individual content blocks, with up to four cache breakpoints per request.

Benefit 4: Better prompt structure

Caching matches the beginning of the prompt exactly. Tools come first, then the system prompt, then the messages, and changing any character invalidates everything after it. This encourages a sensible layout:

• Put stable content first: instructions, tool definitions and reference documents.
• Put content that changes last: the user's question, timestamps and request-specific data.
• Keep the order of tools and JSON fields the same between requests.

Benefit 5: Easy to check

Each response reports usage.cache_creation_input_tokens and usage.cache_read_input_tokens. If cache reads stay at zero for similar requests, something near the start of your prompt is changing.

When it doesn't help

• Prompts shorter than the model's minimum cacheable length aren't cached.
• If requests arrive more than five minutes apart, the cache expires between them. A one-hour cache is available, but writing to it costs more, so compare the numbers.
• Prompts that change at the very beginning on every request never get a cache hit.

When cache reads are zero, the cause is usually small: a date, a request ID or a dictionary with unsorted keys near the top of the prompt.

Turn caching on, check the cache read numbers after a day of normal traffic, and fix whatever is breaking the match.