Did you know · 1 min
Did you know one cache breakpoint covers your whole prompt prefix?
People sprinkle cache_control on every block like seasoning. You need one marker, at the end of the stable part — everything before it rides along. Where you put it decides whether you pay full price for your system prompt on every single call.
There is a myth doing the rounds that you cache a prompt by marking every block
you want cached. So people decorate all their content blocks with
cache_control like it's seasoning, hit the four-breakpoint limit, and start
architecting around a constraint they never had.
One breakpoint caches everything before it. The marker does not say "cache this block" — it says "the prefix ends here". Put it on the last block of the stable part — system prompt, tool definitions, your few-shot examples — and the whole run of it is written once, then read back at a tenth of the input price on every call after that.
The catch people miss, and then blame the API for: the prefix has to be
byte-identical between calls. One timestamp interpolated into your system
prompt — Today is 2026-08-20, 14:32:07 — and congratulations, you are now
paying the cache write premium on every request while reading nothing back.
That is worse than not caching at all, it looks fine in every response, and the
only place it shows is the invoice.
Put anything that changes after the breakpoint. Check the
cache_read_input_tokens field in the response once, actually look at the
number, and then never think about it again.