Enable Prompt Caching

Two Ways to Turn It On

Lesson 121 marked one block with cache_control. The API offers two ways to place cache markers:

Both use the same underlying cache and the same pricing. The difference is who decides where the cache boundary sits: with automatic caching, the API places it on the last cacheable block and moves it forward as the conversation grows.

Automatic Caching

Add cache_control at the top level of the request, next to model and messages:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},            # top-level: automatic caching
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {"role": "assistant", "content": "Nice to meet you, Alex! How can I help today?"},
        {"role": "user", "content": "What did I say I work on?"},
    ],
)

The system caches everything up to and including the last cacheable block. In the next turn, the previous history is read from the cache, and only the new messages are processed. You do not need to move any markers as the conversation grows.

According to the documentation, automatic caching uses one of the four breakpoint slots, which matters when you combine it with explicit breakpoints (Lesson 129).

Explicit Breakpoints

Place cache_control on the blocks where caching should end. Anything before and including that block can be cached:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "You are a legal document assistant."},
        {"type": "text", "text": LONG_AGREEMENT_TEXT,
         "cache_control": {"type": "ephemeral"}},   # cache up to and including this block
    ],
    messages=[{"role": "user", "content": "What is the termination notice period?"}],
)

The first system block is not marked, but it lies before the breakpoint, so it is part of the cached prefix. The breakpoint defines the boundary; the blocks before it are included automatically.

The prefix is built in a fixed order: tools, then system, then messages. A breakpoint caches everything before it in that order.

Choosing Between Them

Automatic caching is the simplest starting point. Explicit breakpoints give precise control, and are needed whenever the cache boundary must sit somewhere other than the end of the request.

Reading the Result

Whichever approach you use, the response's usage fields show what happened:

The total input for the request is the sum of the three (Lesson 125).

Practical Example: Automatic Caching in a Conversation

This example runs a three-turn conversation with automatic caching, and prints the cache fields after each turn. The history grows, and the cached portion grows with it.

"""auto_cache.py: automatic caching across the turns of one conversation."""

from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-opus-5-5"
SYSTEM = (
    "You are a friendly study assistant for an online Python course. "
    "Refer back to earlier messages when they are relevant, and keep answers short. "
    "Follow the course conventions: explain the concept, give one example, and name one pitfall. "
) * 12    # Repeated so the system prompt clears the minimum cacheable length

QUESTIONS = [
    "My name is Priya, and I'm learning Python for a data analysis job.",
    "What is a list comprehension?",
    "Remind me what my job is, and give one example that fits it.",
]


def run_conversation() -> None:
    history: list[dict] = []
    for question in QUESTIONS:
        history.append({"role": "user", "content": question})
        response = client.messages.create(
            model=MODEL,
            max_tokens=400,
            cache_control={"type": "ephemeral"},        # automatic caching
            system=SYSTEM,
            messages=history,
        )
        history.append({"role": "assistant", "content": response.content})
        usage = response.usage
        answer = "".join(b.text for b in response.content if b.type == "text").strip()
        print(f"Q: {question}")
        print(f"   written={usage.cache_creation_input_tokens} read={usage.cache_read_input_tokens} "
              f"uncached={usage.input_tokens}")
        print(f"A: {answer[:90]}\n")


if __name__ == "__main__":
    run_conversation()

Expected output (the answers and token counts vary):

Q: My name is Priya, and I'm learning Python for a data analysis job.
   written=<n1> read=0 uncached=<small>
A: Nice to meet you, Priya! ...

Q: What is a list comprehension?
   written=<n2> read=<n1-ish> uncached=<small>
A: ...

Q: Remind me what my job is, and give one example that fits it.
   written=<n3> read=<n1 + n2-ish> uncached=<small>
A: You're learning Python for data analysis. ...

How It Works

1. cache_control={"type": "ephemeral"} at the top level turns on automatic caching. The request does not need any markers on individual blocks.
2. The history is appended after each answer, so each request contains everything before it. The stored assistant turn is the full response.content, as Lesson 55 requires.
3. Each request reads the earlier turns from the cache and writes the newest ones. The read value grows across turns, while uncached stays small.
4. The system prompt is repeated 12 times only so the example clears the minimum cacheable length. In a real application, the system prompt would simply be long by design.
5. The third answer uses the earlier name and job, which shows that caching does not change what Claude knows from the conversation. It changes only how that history is processed.

Common Mistakes

Forgetting the Minimum Length

What happens: a short conversation shows no cache activity, and the feature appears not to work.

Fix: remember that short prefixes are not cached, and check the usage fields.

Placing Automatic Caching and Explicit Breakpoints Carelessly

What happens: the combination uses up breakpoint slots, or puts the explicit boundary in an unexpected place.

Fix: count slots, and verify where each marker lands (Lesson 129).

Marking a Block That Changes Every Request

What happens: each request writes a new entry, and no reads happen. You pay the write premium every time.

Fix: place the marker on the last block that stays the same.

Mixing Up input_tokens

What happens: input_tokens looks small, and the cost seems lower than it is.

Fix: add all three input fields for the true total (Lesson 125).

Best Practices

• Start with automatic caching for conversations.
• Use explicit breakpoints for stable documents, system prompts, and tools.
• Keep the cached prefix stable from request to request.
• Check the usage fields on the first few requests of every new feature.
• Use the same model across requests that should share a cache, because each model keeps its own entries.

Exercise

1. Change MODEL to claude-sonnet-5-5, and compare the fields. Does the first request write to the cache?
2. Remove the * 12 from SYSTEM. What changes in the output?
3. Replace automatic caching with an explicit breakpoint on the system block. Do the usage numbers change?
4. Explain why history.append({"role": "assistant", "content": response.content}) must store the full content rather than the text alone.

Step 3: the numbers should be similar, because both approaches cache the same prefix. The difference is that the explicit breakpoint covers only the system prompt. The conversation history after it is then not cached automatically, so the read value grows more slowly on turns 2 and 3. Automatic caching is the better choice when the conversation itself is the growing prefix.

Step 4: the stored history must match what the API produced, including any thinking blocks and other content. Keeping the full content preserves the exact prefix, which is what allows later requests to match the cache. Storing only the text would change the prefix, and a changed prefix cannot be read from the cache.