Building with the Claude API · lesson 11 of 17

Prompt Caching

A massive cost and latency lever. Mark a prefix as cacheable; subsequent calls that share that prefix read it from the server cache at ~10% of input cost and much lower latency.

How to enable

Add cache_control: {type: "ephemeral"} to a content block:

system=[
    {"type": "text", "text": "You are an expert tax preparer."},
    {
        "type": "text",
        "text": LARGE_TAX_CODE,  # the cacheable prefix
        "cache_control": {"type": "ephemeral"},
    },
]

You can also cache:

Tool definitions (tools=[..., {"cache_control": {"type": "ephemeral"}}])
Messages content blocks
Documents (PDFs, code) inserted into user turns

TTL

Default ephemeral cache: 5 minutes after last use.
A 1-hour cache tier also exists ({"type": "ephemeral", "ttl": "1h"} where supported).
Each access bumps the TTL.

This 5-minute window drives a lot of design — if requests are spaced further apart, you pay full price.

Breakpoints

You set up to 4 cache breakpoints per request. Each breakpoint marks "everything up to and including this block is cacheable as one unit."

A common pattern:

[system: persona]  → breakpoint 1 (always cached)
[system: reference doc]  → breakpoint 2 (cached, refreshed when doc updates)
[messages: long convo history]  → breakpoint 3 (cached up to last user turn)

Pricing model

Cache write (first time): higher than regular input cost (~125%).
Cache read (subsequent): ~10% of regular input cost.

So caching pays off after ~2 reuses of the cached prefix.

Cache hit indicators

The response usage block tells you:

"usage": {
  "input_tokens": 50,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 12000,
  "output_tokens": 200
}

Treat cache_read_input_tokens > 0 as a hit. Treat sustained cache_creation traffic as a problem (you're churning the cache).

Cache invalidation

Any change to the cached prefix invalidates it:

Adding/removing a tool.
Changing a single character in the system prompt.
Different model ID.

Keep cacheable prefixes stable. Put volatile data (timestamps, user IDs) after the breakpoint.

CALM framework

In the CCA-F exam, "CALM" is cited as a mnemonic for context management:

Cache — mark stable prefixes
Align — keep prefix structure stable across requests
Limit — bound conversation history
Monitor — track cache hits, token budgets