Claude and the Anthropic SDK · Chapter 13 of 21

Prompt caching

By the end of this chapter you can mark the parts of a request that never change so Claude reads them from a cache instead of processing them again, read the cache's two usage fields, cache a growing conversation with automatic caching, put a breakpoint at the end of a shared document rather than on a question that changes, and say why a short prompt never caches at all. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Cost
  • 4 tasks
  • Python
  • In the all labs plan

The first 2 chapters of Claude and the Anthropic SDK are free. This one comes with the all labs plan.

Why you need this

Sahay sends Parchi's policy wording with every question: 2,990 tokens of the same text, again and again. Farhan has added it up. Four hundred bills a week, several questions a bill, and on Opus 5.5 each copy of the policy costs $0.012 before Claude has written a word. Almost all of Sahay's input is the same bytes as last time.

With the OpenAI-style API you may never have thought about this: caching happens there on its own, and a cached_tokens count shows up afterwards. Claude's API makes it explicit. You say where the reusable part ends with a cache_control marker; a cache write costs a little more than normal input, and a cache read costs a twentieth of it on Opus 5.5. Put the marker in the right place and the policy costs almost nothing after the first question. Put it in the wrong place and you pay the extra for writes that are never read.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    cache_the_policy.py: cache the policy

    Send system as two text blocks: INTRO (given), then policy_wording() with "cache_control": {"type": "ephemeral"}. Ask the two QUESTIONS (given) one after the other: model "claude-opus-5-5", max_tokens 1024, one user message each.

    After each reply print request N: I in, W written, R read, from usage.input_tokens, cache_creation_input_tokens and cache_read_input_tokens. The second request must read the cache.

  2. Task 2

    kamla_chat.py: a conversation that caches as it grows

    For each of TURNS (given): append the user message, send model "claude-opus-5-5", max_tokens 1024, system=SYSTEM (given), the whole messages list, and a top-level cache_control={"type": "ephemeral"}; append {"role": "assistant", "content": reply.content}; print turn N: I in, W written, R read from usage.

    Every turn must read more from the cache than the turn before.

  3. Task 3

    one_summary_three_questions.py: one document, three questions

    For each of QUESTIONS (given), one after the other, send model "claude-opus-5-5", max_tokens 2048, system=policy_wording() (a string) and one user message of two blocks: a document block with pdf(PDF) as its source and "cache_control": {"type": "ephemeral"}, then the question as a text block with no marker. No top-level cache_control.

    After each reply print question N: I in, W written, R read. Questions 2 and 3 must read the document from the cache.

  4. Task 4 · interview question

    Interview: too_short.py

    "Caching does nothing for the inbox classifier. Why?" Classify MESSAGES (given) one after the other: model "claude-haiku-5-5", max_tokens 64, system: one text block CLASSIFY with "cache_control": {"type": "ephemeral"}, the message's text as the one user message.

    After each reply print ID: LABEL (W written, R read). Then print prompt: N tokens, under 512: yes (or no), where N is the first request's input_tokens + cache_creation_input_tokens + cache_read_input_tokens.

What you will learn

  • cache_control: a breakpoint that caches everything before it.
  • The usage fields: cache_creation_input_tokens and cache_read_input_tokens.
  • Render order: tools, then system, then messages, and what that means for a prefix.
  • The rules: at most 4 breakpoints, the 512-token minimum, 5 minutes by default.
  • Automatic caching for a growing conversation.
  • Shared prefix, changing question: where the breakpoint goes.

More in Cost

Build "Prompt caching" yourself

Parchi, a Jaipur startup, helps families claim health insurance. You build Sahay, a claims assistant that reads bills and policies with Claude, and measure what caching, models and effort cost. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Claude and the Anthropic SDK are free. This one comes with the all labs plan.