Claude Prompt Caching in TypeScript (With Cost Math)

Cache a large document in the system prompt and log what each call wrote and read.

import Anthropic from "@anthropic-ai/sdk";
import { readFile } from "node:fs/promises";

const client = new Anthropic();
const handbook = await readFile("./docs/handbook.md", "utf8"); // tens of thousands of tokens

async function ask(question: string) {
  const res = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    system: [
      { type: "text", text: "Answer only from the handbook below. Quote section titles." },
      {
        type: "text",
        text: handbook,
        cache_control: { type: "ephemeral" }, // cache everything up to here
      },
    ],
    messages: [{ role: "user", content: question }],
  });

  const u = res.usage;
  console.log({
    wrote: u.cache_creation_input_tokens, // > 0 on the first call
    read: u.cache_read_input_tokens,      // > 0 on later calls
    uncached: u.input_tokens,             // tokens after the breakpoint
  });
  return res;
}

await ask("What is the leave policy for contractors?");
await ask("Who approves expense claims over ₹50,000?");

Automatic caching for a multi-turn chat: one top-level field, no per-block bookkeeping.

const res = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" }, // automatic breakpoint placement
  system: SYSTEM_PROMPT,
  messages: history, // grows every turn
});