Skip to content

Prompt caching: stop paying full price for the same long prompt

From the work/ 11 min read

Prompt caching in the Claude API: put the fixed part first, mark it with cache_control, and check the usage fields to see what you saved. TypeScript code and a PDF guide.

  • AI
  • Node.js
In this article (8)
  1. What each call bills without prompt caching
  2. Fixed content first, variable content last
  3. Mark the block with cache_control
  4. How long the cache lasts and what invalidates it
  5. Measure the savings with the response usage fields
  6. Common mistakes
  7. Frequently asked questions
  8. Checklist

Prompt caching lets the Claude API store the fixed part of your prompt (instructions, tools, a catalog) and read it back on later calls at a fraction of the input price. You put the fixed part first, mark it with cache_control and keep the variable part last. Without it, every call bills the whole prompt again.

Below: what each call bills, how to order the prompt, TypeScript code with the official SDK, how long the cache lasts, what invalidates it and how to measure the savings from the usage fields. Rules and prices come from Anthropic's prompt caching docs and pricing page, read on November 19, 2026. The code was tested against a fake client, without calling the API.

What each call bills without prompt caching

The API keeps no state between calls. Every request sends the whole prompt: tool definitions, system instructions, the conversation so far and the new question. Every input token is billed at the model's base price, even when it is byte for byte what you sent ten seconds ago. If your store assistant carries 20,000 tokens of policies and catalog in system, a hundred questions are two million input tokens, nearly all of them repeats.

Tools count too. If you read function calling explained with a shopping cart, the JSON schema of every tool travels as input tokens on every request. In a long chat the history also grows with each turn, which is the same reason the Claude Code usage limit runs out; Claude Code applies the cache for you.

With prompt caching, the first call writes the prefix to the cache and the next calls read it. A write costs a little more than normal input and a read costs far less. Per the docs, a 5-minute write is 1.25 times the base input price, a 1-hour write is 2 times, and a read is 0.1 times on most models; on Claude Opus 5.5 and Sonnet 5.5 a read drops to 0.05 times. These are the per-million-token prices published on November 19, 2026:

ModelBase input5-min write1-hour writeCache readMinimum cacheable
Claude Opus 5.5$4$5$8$0.20 (0.05x)512 tokens
Claude Sonnet 5.5$2$2.50$4$0.10 (0.05x)512 tokens
Claude Sonnet 5$2$2.50$4$0.20 (0.1x)1,024 tokens
Claude Haiku 5.5 (prompts up to 100,000 tokens)$0.10$0.125$0.20$0.01 (0.1x)512 tokens
Claude Haiku 4.5$1$1.25$2$0.10 (0.1x)4,096 tokens

The break-even math is short. On Opus 5.5, a 5-minute write costs 0.25 times extra and every read saves 0.95 times, so a single read pays for the write. A 1-hour write costs 1 time extra, so you need two reads. The multipliers stack with other pricing modifiers such as the Batch API discount and data residency. If a prefix is only ever used once, caching it costs you more.

Fixed content first, variable content last

The cache works on prefixes. The docs say the prefix is built in this order: tools, then system, then messages. A read only happens when everything before the marked point is identical, byte for byte, to an earlier request. Change something at one level and that level, plus everything after it, stops matching.

That gives you the ordering rule: what never changes goes on top, what changes on every call goes at the bottom. Tool definitions, always in the same order. System instructions, with no date or user name in them. Long documents such as policies or a catalog. Then the conversation history. The new question goes last.

the prompt as a stack: fixed on top, variable at the endtools · tool definitionssystem · instructionssystem · policies and catalogmessages · historymessages · new questioncache_controlfixed: identical on every callwritten once (1.25x)then read from the cachevariable: changes every callbilled at the normal priceprefix order: tools, system, messagessource: Anthropic prompt caching docs

Scroll the figure sideways to see all of it

There is a minimum. A prefix shorter than the model's minimum is not cached, and the API returns no error; it just bills everything as normal input. On Opus 5.5, Sonnet 5.5 and Haiku 5.5 the minimum is 512 tokens; on Sonnet 5, 1,024; on Haiku 4.5, 4,096. A three-line system prompt gains nothing.

With RAG, the chunks you retrieve change with every question, so they belong after the marked point. If your knowledge base is small, the alternative is to put all of it in the prompt and cache it; the RAG chatbot over your documents article covers when each approach makes sense.

what is worth caching, and where it goescontentcache it?wheretool definitionsyesstart of the prefixsystem instructionsyesbefore the breakpointcatalog, policies, documentsyesbefore the breakpointconversation historyyesbreakpoint at its endper-question RAG chunksnoafter the breakpointdate, time, session idnoafter it, or not at allthe user's questionnoat the endone different byte before the breakpoint and there is no readstable first, changing lastup to 4 breakpoints per request, per the docs

Scroll the figure sideways to see all of it

Mark the block with cache_control

There are two ways to turn it on. Automatic caching is one cache_control field at the top level of the request: the API places the breakpoint on the last cacheable block and moves it forward as the conversation grows, which suits multi-turn chats. Explicit breakpoints put cache_control on the exact block where the fixed part ends. You can use up to 4 breakpoints per request. Here is the explicit version, a store assistant with its policies in system:

// ask.ts
import { readFileSync } from "node:fs";
import type Anthropic from "@anthropic-ai/sdk";

export const MODEL = "claude-opus-5-5";

// Fixed part: read once at startup, the same bytes on every call.
const POLICIES = readFileSync(new URL("./policies.md", import.meta.url), "utf8");

export const SYSTEM: Anthropic.TextBlockParam[] = [
  { type: "text", text: "You answer customer questions for an online store. Use only the policies below." },
  // Breakpoint: everything up to and including this block is cached.
  { type: "text", text: POLICIES, cache_control: { type: "ephemeral" } },
];

// Variable part: the question goes last, after the breakpoint.
export function ask(client: Anthropic, question: string) {
  return client.messages.create({
    model: MODEL,
    max_tokens: 1024,
    system: SYSTEM,
    messages: [{ role: "user", content: question }],
  });
}
  1. MODEL is the Claude Opus 5.5 id, the one the docs' examples use.
  2. POLICIES is read once at startup. It is not rebuilt from a template on each request, so no date or stray whitespace can sneak in.
  3. SYSTEM is a list of blocks: the instructions first, then the policies.
  4. cache_control: { type: "ephemeral" } on the second block is the breakpoint: everything up to and including that block is written to the cache on the first call and read afterwards.
  5. ask only changes the question, which goes in messages, after the breakpoint. The prefix is identical on every call.

For a one-hour lifetime, the block takes cache_control: { type: "ephemeral", ttl: "1h" }. If your tool definitions are long, put the breakpoint on the last tool in the tools list, which is the first part of the prefix. One more detail: each breakpoint looks back at most 20 positions for an earlier write. In a very long conversation, add another breakpoint before you cross that limit, or use automatic caching.

How long the cache lasts and what invalidates it

The default lifetime is 5 minutes, refreshed at no cost every time the entry is read. If your traffic has longer gaps, the 1-hour option costs twice the base price to write but survives the pause. Note that the docs measure the lifetime from the start of the request that writes or reads the entry, not from the end of its response, so a long answer eats into the window. There is no way to clear the cache by hand; entries expire on their own.

What invalidates it, according to the table in the docs:

  • Any change to the content before the breakpoint: one character, a new line, a timestamp.
  • Changing tool definitions: invalidates tools, system and messages.
  • Changing tool_choice, or adding or removing images anywhere: invalidates messages; tools and system still match.
  • Turning web search or citations on or off: invalidates system and messages.
  • Changing thinking parameters or the effort setting: invalidates messages, and on some models system and tools too.

Caches are never shared between organizations, even for identical prompts, and on the Claude API they are also isolated per workspace.

Measure the savings with the response usage fields

Every response carries a usage object, and three fields tell you what happened to the input: cache_creation_input_tokens is what was written to the cache, cache_read_input_tokens what was read from it, and input_tokens what came after the last breakpoint. That last one is not the total. The docs give the formula: total input = read + creation + input_tokens. With that, you can price every call:

// cost.ts
import type Anthropic from "@anthropic-ai/sdk";

// USD per million tokens for Claude Opus 5.5, from the pricing page on 2026-11-19.
export const PRICE = { input: 4, write5m: 5, write1h: 8, read: 0.2, output: 20 };

export function cost(u: Anthropic.Usage, p = PRICE) {
  const written = u.cache_creation_input_tokens ?? 0;
  const read = u.cache_read_input_tokens ?? 0;
  const w1h = u.cache_creation?.ephemeral_1h_input_tokens ?? 0;
  const usd =
    (u.input_tokens * p.input + (written - w1h) * p.write5m + w1h * p.write1h +
      read * p.read + u.output_tokens * p.output) / 1e6;
  const total = read + written + u.input_tokens; // the docs' total input formula
  return { usd, total, hitRate: total ? read / total : 0, cached: written + read > 0 };
}

// run.ts
import Anthropic from "@anthropic-ai/sdk";
import { ask } from "./ask.ts";
import { cost } from "./cost.ts";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from the environment

for (const q of ["Do you ship to Monterrey?", "Can I return a gift?"]) {
  const { usage } = await ask(client, q);
  const c = cost(usage);
  console.log(
    `write ${usage.cache_creation_input_tokens} · read ${usage.cache_read_input_tokens}` +
      ` · new ${usage.input_tokens} · $${c.usd.toFixed(4)}`,
  );
  if (!c.cached) console.warn("no cache: prefix under the model minimum, or no breakpoint");
}
  1. PRICE holds the Opus 5.5 prices per million tokens. Switch models, switch this table.
  2. written and read pick up the two cache fields; the SDK types them as number | null, hence the ?? 0.
  3. w1h splits out what was written with a 1-hour lifetime, reported in cache_creation.ephemeral_1h_input_tokens and priced differently.
  4. usd multiplies each kind of token by its price and divides by a million.
  5. total applies the docs' formula, and hitRate is the share of input that came from the cache.
  6. cached is false when both fields are 0: the prefix was under the minimum, or there is no breakpoint.
  7. run.ts asks two questions in a row and prints one line per call.

This is what run.ts printed against the fake client, which counts tokens as characters divided by four (these are not Claude's token counts):

write 4533 · read 0 · new 12 · $0.0247
write 0 · read 4533 · new 12 · $0.0030

The first call writes, the second reads. If the second call shows another write instead of a read, something in the prefix changed. To see the effect at volume, here is an illustrative scenario computed from the price table, not a measurement: a 20,000-token prefix, a 200-token question, a 300-token answer, every call inside the 5-minute window. Without the cache, a hundred calls cost $8.68; with it, $1.18. On input alone, spend drops from $8.08 to $0.58, 93% less. With a single call the cache costs more: $0.1068 against $0.0868.

cost with and without the cache (illustrative)dark bar: no cache · colored bar: with cache1 call$0.0868$0.106810 calls$0.8680$0.2040100 calls$8.68$1.18with a single call the cache costs more: a write is 1.25xeach row on its own scaleOpus 5.5 · 20,000-token prefix, 200-token question, 300-token answer

Scroll the figure sideways to see all of it

Common mistakes

  • A date or time in the system prompt. It changes on every call, the prefix never matches, and you pay the 1.25x write every time. Move it after the breakpoint or drop it.
  • The breakpoint on the block that changes. With cache_control on the user's question, every call writes a new entry and nothing is ever read.
  • Tools in a different order. If you build them from an object or a query with no fixed order, the JSON changes and the whole cache is invalidated.
  • A prefix under the minimum. No error, just no caching. Check that the two cache fields are not both 0.
  • Reading input_tokens as the total. It only covers what comes after the last breakpoint; add up all three fields.
  • Caching something used once. A write costs more than normal input; with no reads, you lose money.
  • RAG chunks before the breakpoint. They change with every question and break the prefix for everything behind them.

Frequently asked questions

How many tokens does a prompt need before it is cached?

It depends on the model: 512 tokens on Opus 5.5, Sonnet 5.5 and Haiku 5.5; 1,024 on Sonnet 5; 4,096 on Haiku 4.5. A shorter prefix is processed without the cache, with no warning.

Should I use the 5-minute or the 1-hour cache?

The 5-minute cache when calls arrive close together, since every read refreshes it for free. The 1-hour cache when there are long gaps between calls or slow responses; it costs 2 times the base price to write and needs at least two reads to pay off.

Can I clear the cache?

No. The docs say there is no way to clear it by hand: entries expire on their own after the idle time. If you change the prompt, the next call simply writes a new entry.

Can another account read what I cached?

No. Caches are never shared between organizations, even for identical prompts, and on the Claude API they are also separated by workspace. The cache key is a hash of the prompt up to the breakpoint.

Checklist

  • The prompt is in order: tools, instructions, documents, history, question.
  • Nothing before the breakpoint changes between calls: no dates, ids or names.
  • Tools always come out in the same order.
  • cache_control sits on the last fixed block, not on the question.
  • The prefix is over the model's minimum.
  • You picked 5 minutes or 1 hour based on how often calls arrive.
  • You log the three input fields and the read rate.
  • The prices in your math match the pricing page for your model.

With a stable prefix, every repeated call pays a fraction of what it used to. If your prompt also carries tools, the next step is the function calling loop.

Saw this on Instagram? Every Reel guide is at ecomlabs.dev/guides.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026 · updated November 20, 2026

← Blog