Cut API costs with prompt caching

Cache the long instructions and documents you resend with every request, and their input cost drops sharply. Using a support bot built on a manual, here's how to place the cache point and check that it works.

Step by step

1. 1

   What caching saves

   A support bot that sends long instructions and a manual with every question pays input prices for the same content again and again. Prompt caching stores the front part of a request for a while, and when the next request starts with exactly the same content, it reuses what was stored.

   Storing it the first time (a cache write) costs a little more than normal input; reusing it (a cache read) costs far less. Output prices, and the answers themselves, stay the same with caching.

   Caching-related prices for claude-opus-5-5 (per million tokens, October 2026)

   Item	Price	Versus base input
   Base input	$4	1×
   Cache write (5-minute lifetime)	$5	1.25×
   Cache write (1-hour lifetime)	$8	2×
   Cache read	$0.20	0.05×
   Output	$20	Unaffected by caching

   Check it

   • The cache-read multiplier differs by model (0.1× base input on most). Start by checking the price list for your model.
2. 2

   Unchanging content first, changing content last

   The cache reuses only the part of a request that is identical, character for character, from the very start. Requests are processed in the order tools (tool definitions), system, messages, so unchanging content like the manual goes first and content that changes every time, like the customer's question, goes last.

   Put the cache_control marker on the last block that's identical in every request: the end of the manual. Put it on the question, which changes every time, and each request writes a fresh entry that's never read back.

   A common mistake is putting the current time or the user's name at the very start of the system prompt. The opening then differs on every request, so nothing after it, the manual included, ever hits the cache.

   How the support bot's request is laid out, and where the cache point goes (example)

   Order	Contents	Cache
   1. tools	Tool definitions (none in this example)	Cached with the rest if unchanged
   2. system	A one-line role instruction + the support manual (about 20,000 tokens)	cache_control at the end of the manual block
   3. messages	The customer's question (changes every time)	Not cached

3. 3

   Add cache_control

   Write system as a list of blocks instead of a string, and you can put cache_control on any block. Add {"type": "ephemeral"} to the manual block and everything up to and including it is cached.

   A cache entry lives for 5 minutes by default, and each read resets it to 5 minutes at no extra cost. If your requests come more than 5 minutes but less than an hour apart, "ttl": "1h" extends the lifetime to an hour, but weigh that against writes then costing twice the base input price.

   I'm writing Python code that puts a support manual (about 20,000 tokens) in the system prompt and answers customer questions. The manual never changes; only the question does.
   Write anthropic SDK code that reuses the manual through prompt caching. The model is claude-opus-5-5.

   Put the cache point at the end of the manual block, and the changing question after it, in messages.

   Example codeCopy

   import anthropic client = anthropic.Anthropic() with open("manual.txt", encoding="utf-8") as f: manual = f.read() # the support manual, which never changes def ask(question): return client.messages.create( model="claude-opus-5-5", max_tokens=1024, system=[ {"type": "text", "text": "You are our online store's support agent. Answer only from the manual below."}, {"type": "text", "text": manual, "cache_control": {"type": "ephemeral"}}, ], messages=[{"role": "user", "content": question}], )

   system=[{...}, {...}]

   Writing system as a list of blocks lets you mark individual blocks for caching.

   "cache_control": {"type": "ephemeral"}

   Caches everything from the tool definitions up to and including this block. The default lifetime is 5 minutes.

   messages=[{"role": "user", "content": question}]

   The question, which changes every time, goes after the cache point.

   Check it

   • Measure the manual first with client.messages.count_tokens (token counting is free). claude-opus-5-5 won't cache a prefix shorter than 512 tokens.
4. 4

   Check for cache hits in usage

   With caching, read three values together in the response's usage. cache_creation_input_tokens is what was newly written to the cache, cache_read_input_tokens is what was read from it, and input_tokens is what came after the last cache point and was processed without the cache.

   The three add up to the whole input you sent. Below are three questions sent with the same manual. The third went out 10 minutes later, after the entry had expired, so it was written again.

   usage for three questions (example)

   Request	Cache write (creation)	Cache read (read)	Other input (input)
   1st	20,000	0	200
   2nd (1 minute later)	0	20,000	180
   3rd (10 minutes later)	20,000	0	210

   I added caching, but every request shows about 20,000 cache_creation_input_tokens and cache_read_input_tokens stays at 0. I send a few requests a minute.
   The first system block starts with the request time, like 'Current time: 2026-10-20 14:03:12'. What's wrong?

   The time in the first block is the cause. The cache reuses only content that's identical from the start, and because the time changes on every request, everything after it, the manual included, becomes a different prefix each time. So each request writes a new entry and none is ever read.

   Move the time after the cache point, into the same message as the customer's question. The instruction and manual are then identical every time, and from the second request on, cache_read_input_tokens should show about 20,000 tokens.

   Check it

   • Send two requests with the same manual within 5 minutes and check that cache_read_input_tokens is above 0 on the second.
   • If creation and read are both 0, nothing was cached at all; usually the prefix is shorter than the minimum or cache_control is missing. If creation shows up every time and read stays at 0, something before the cache point changes between requests.
5. 5

   Work out the savings

   A cache write costs 25% more than base input, but on claude-opus-5-5 a single read already more than makes up for it. The more often you resend the same prefix, the more you save.

   If requests come further apart than the cache lifetime, though, every request pays for a fresh write and you pay 25% more, not less. Features that are called rarely may not benefit from caching at all.

   100 requests in an hour (manual 20,000, question 200, answer 400 tokens; claude-opus-5-5)

   Item	Without caching	With caching
   Manual, 20,000 tokens	100 × $0.08 = $8.00	1 write $0.10 + 99 reads × $0.004 = $0.496
   Question, 200 tokens	$0.08	$0.08
   Answer, 400 tokens	$0.80	$0.80
   Total	$8.88	$1.376

   I send 100 requests an hour, each with a 20,000-token manual, a 200-token question and a 400-token answer. Requests are always less than 5 minutes apart.
   Using claude-opus-5-5 prices (per million tokens: input $4, 5-minute cache write $5, cache read $0.20, output $20), compare the cost with and without caching, showing your working.

   Without caching: per request, input is 20,200 tokens × $4 ÷ 1,000,000 = $0.0808 and output is 400 tokens × $20 ÷ 1,000,000 = $0.008, so $0.0888. 100 requests come to $8.88.

   With caching: the manual is written once on the first request (20,000 × $5 ÷ 1,000,000 = $0.10) and read on the other 99 (20,000 × $0.20 ÷ 1,000,000 = $0.004 each, $0.396 in all). Add $0.08 for the questions and $0.80 for output: $1.376.

   That's about 84.5% less over 100 requests. Only the input cost of the manual shrank; output costs the same.

   Check it

   • After a few days in production, compare the total cache_read_input_tokens in your usage logs with total input. If the share read from the cache is low, revisit the ordering from step 2 and the gaps between requests.