How to use Claude prompt caching to reduce API cost

Claude caches only what you mark. A cache breakpoint is a cache_control field, {"type": "ephemeral"}, on a content block. Everything up to and including that block becomes the cached prefix. Claude assembles a prompt in a fixed order, tools first, then the system prompt, then messages, so a breakpoint on the last system block caches the tools and the system prompt together.

You can set up to four breakpoints in one request, so the long-lived part (tools and instructions) and the growing part (the conversation) are cached separately. Or put one cache_control at the top level of the request: Claude then caches everything up to the last block and moves the breakpoint forward as the conversation grows.

A hit needs an exact prefix match on the same model. Prefixes shorter than the model's minimum length are not cached at all; Anthropic's caching guide lists the minimum for each model.

A Claude response splits its input into three counts, each with its own price:

A write costs a little more than plain input, and a read costs a small fraction of it. On claude-sonnet-5.5, for example, the docs list the cache write at 1.25 times the uncached input price and the cache read at one twentieth of it. Caching therefore pays for itself on the second request: one write plus one read comes to 1.3 times the input price for the prefix, against 2 times for sending it uncached twice.

The table shows live input, output and cache-read prices for every Claude model. Each model's page, such as Claude Sonnet 5.5, also lists the cache-write price, and Models & pricing has the formula for one call.

Anthropic keeps a cache entry for five minutes by default, and every read resets that timer. A conversation whose turns arrive less than five minutes apart keeps its cache warm for as long as it runs. One that pauses for longer pays for a fresh write on its next turn, then reads again from there.

Because the match is on exact bytes, any change in the prefix invalidates the cache from that point on:

A cache lives on the channel that wrote it. A gateway that spreads requests over several channels could send turn two of a conversation to a different channel than turn one, and turn two would pay for a new write instead of a read.

Lovely Router keeps each conversation on the channel that holds its cache. It fingerprints a conversation from its system prompt plus its first user message, which stay the same as a chat grows, so this works without code changes. Claude Code's session header, metadata.user_id or an x-session-id header take priority when present. A pin lasts up to an hour and renews while the conversation is active. If the pinned channel is busy, the turn waits briefly rather than paying for a new write; if it fails, the turn moves to a healthy channel and the pin follows.

Send your own x-session-id when your app changes the first user message between turns, for example when it summarizes old history. Prompt caching lists every rule.

This chat answers questions about a long handbook. The handbook goes in a system block with a breakpoint, and a top-level cache_control caches the conversation as it grows. Install the SDK with pip install anthropic, create a key in API keys and export it as LOVELY_API_KEY.

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://lovelyrouter.com",
    api_key=os.environ["LOVELY_API_KEY"],
)

HANDBOOK = open("handbook.md").read()  # long, stable reference text
history = []


def ask(question):
    history.append({"role": "user", "content": question})
    response = client.messages.create(
        model="claude-sonnet-5.5",
        max_tokens=1024,
        system=[{
            "type": "text",
            "text": HANDBOOK,
            "cache_control": {"type": "ephemeral"},  # breakpoint 1: the handbook
        }],
        cache_control={"type": "ephemeral"},  # breakpoint 2: the conversation so far
        messages=history,
        extra_headers={"x-session-id": "handbook-chat-1"},  # optional: one id per conversation
    )
    history.append({"role": "assistant", "content": response.content})

    u = response.usage
    written = u.cache_creation_input_tokens or 0
    read = u.cache_read_input_tokens or 0
    total = u.input_tokens + written + read
    print(f"written {written}, read {read}, uncached {u.input_tokens}, hit rate {read / total:.0%}")
    return next(block.text for block in response.content if block.type == "text")


print(ask("What is the refund window?"))
print(ask("Does it apply to digital goods?"))

The first call writes the handbook and the first question, so written is large and read is zero. From the second call on, read covers everything sent before and written only the newest answer and question. If an older anthropic package rejects the top-level cache_control argument, upgrade it or keep only the system breakpoint. If both counts stay at zero, the handbook is below the model's minimum.

Hit rate is the share of input read from the cache: cache_read_input_tokens divided by all three input counts. You can see it in three places:

Affinity shows whether routing kept the cache reachable: sticky means the turn went back to its conversation's channel, explicit that you sent a session id, new that it was a first call or its pin had expired.