Prompt caching · Context is everything

Lots of requests start the same way: the same instructions, the same handbook, the same long chat history, and only the last bit changes. Prompt caching lets Claude keep the work it did on that shared start, so the next request that begins with exactly the same text skips straight to the new part. It's cheaper, and faster to the first token on long prompts.

The rule that makes or breaks it: caching is a prefix match. Claude reads a request in a fixed order (tools, then the system prompt, then the messages) and a cache hit needs every token up to your cache marker to be identical. Change one character early on, and everything after it misses.

So put what never changes first, and what changes every time last:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

export async function askHandbook(handbook: string, question: string) {

const res = await client.messages.create({

model: "claude-haiku-5-5",

max_tokens: 1024,

system: [

{ type: "text", text: "Answer staff questions from the handbook. Quote it." },

{

type: "text",

text: `<document>${handbook}</document>`,

cache_control: { type: "ephemeral" }, // cache everything up to here

messages: [{ role: "user", content: question }], // changes every time

});

console.log(res.usage.cache_creation_input_tokens, res.usage.cache_read_input_tokens);

return res;

}

TypeScriptUTF-8● lines 9–13: highlighted

The first call writes the cache; the next ones read it. This is example output, not a live run:

OUTPUT

npx tsx handbook-bot.ts

question 1 cache_creation=50,214 cache_read=0

question 2 cache_creation=0 cache_read=50,214

question 3 cache_creation=0 cache_read=50,214

example output · one write, then reads

For a chat, there's a shortcut: put one cache_control at the top level of the request and the API moves the marker forward to the newest message for you (Anthropic calls this automatic caching).

The price, as of October 2026. Writing to the cache costs a bit more than normal input: 1.25× for the default cache. Reading from it costs 0.1×, and less on some models (0.05× on Opus 5.5 and Sonnet 5.5). On Haiku 5.5 that's $0.125 per million tokens to write and $0.01 to read, against $0.10 uncached.

Say staff ask 10 questions about a 50,000-token handbook in a few minutes. Uncached, that's 10 × 50,000 tokens at $0.10 per million: $0.05. Cached, it's one write ($0.00625) plus nine reads ($0.0045): about $0.011, nearly 80% less.

The fine print. The cache lives for 5 minutes and every hit resets the clock for free. A 1-hour cache exists, at 2× the write price, for traffic with longer gaps. On current models a prefix shorter than 512 tokens isn't cached at all, and you get no error, so check cache_read_input_tokens in the response. And cached tokens still take up room in the window: caching changes what you pay, not what fits.

Down the rabbit hole