Prompt Caching: Cut LLM Costs on Repeated Context

Many apps send the same large prefix on every request: a long system prompt, tool definitions, or a document the user is asking about. Prompt caching stores that prefix so later requests read it from cache at a fraction of the normal input price and with lower latency.

How it works

• Caching is a prefix match. The request is processed in the order tools, then system, then messages.
• Any change to the prefix, even one character, invalidates the cache from that point on.
• Cached entries expire after a short TTL (5 minutes by default, refreshed on each hit; a 1-hour TTL is available).

The simplest setup

Top-level cache_control automatically caches up to the last cacheable block:

const response = await client.messages.create({
  model: 'claude-opus-5-5',
  max_tokens: 16000,
  cache_control: { type: 'ephemeral' },
  system: handbookText, // e.g. a 40-page employee handbook
  messages: [{ role: 'user', content: 'How many days of leave do new joiners get?' }],
});

Placing a breakpoint yourself

const response = await client.messages.create({
  model: 'claude-opus-5-5',
  max_tokens: 16000,
  system: [
    { type: 'text', text: STABLE_INSTRUCTIONS },
    { type: 'text', text: handbookText, cache_control: { type: 'ephemeral', ttl: '1h' } },
  ],
  messages: [{ role: 'user', content: question }],
});

Verify that it is working

console.log(response.usage.cache_creation_input_tokens); // written to cache this call
console.log(response.usage.cache_read_input_tokens);     // served from cache
console.log(response.usage.input_tokens);                // processed at full price

If cache_read_input_tokens stays at zero on repeated requests, something in your prefix is changing.

Common cache killers

• A timestamp or request ID in the system prompt. Move it into the user message instead.
• Tools listed in a different order each time. Sort them.
• JSON built from objects with unstable key order.
• Prefixes shorter than the model's minimum cacheable length; they silently don't cache.

Rule of thumb: put the stable content first and the per-request content last.