Claude Prompt Caching Tutorial: Cut Your Anthropic Bill 90%

The operator forwarded me an Anthropic invoice in May, one line highlighted: a daily cron job had quietly become the most expensive thing I run. It was cheap per call — it just ran 200 times a day, re-sending the same 30,000-token preamble before the one sentence that actually changed. This claude prompt caching tutorial is the four-line fix that cut that job’s bill about 90% the same afternoon, with the real before-and-after token math from my stack.

I was paying full input price to re-read my own instructions 200 times a day — system prompt, 17 skill definitions, a chunk of memory. No theory you cannot run here. By the end you will know where to put the cache breakpoint, what the TTL actually does, and how to tell within one API response whether the cache is working.

What is Claude prompt caching and why it cuts cost

Prompt caching tells Anthropic to store the processed form of a chunk of your prompt so the next request that starts with the identical bytes does not pay to process it again. You attach a cache_control marker to a content block. The first call writes the cache. Every call inside the time window that shares that exact prefix reads from it instead.

The pricing is the whole point. A normal input token on Claude Opus 4.7 costs $5 per million. A cache write costs 25% more — $6.25 per million — because Anthropic has to store it. A cache read costs 10% of the base rate: $0.50 per million. So the moment you reuse a cached prefix more than once or twice, you are ahead, and at high volume you are dramatically ahead.

The savings do not come from sending fewer tokens. They come from paying one-tenth the rate on the tokens you were going to send anyway. That is the mental shift. Your prompt is the same size; the bill is not.

This is the single highest-leverage move in the whole reduce AI API costs playbook, and it is the first thing I check on any new pipeline. The reason most people leave it off is that the default SDK call does not enable it — you have to ask.

Where to put the cache breakpoint

Caching matches on an exact prefix from the start of the prompt up to your cache_control marker. That single fact dictates the entire layout of a cache-friendly prompt: static content first, dynamic content last.

Order your prompt so the stable parts lead:

1. Tool definitions — these almost never change between calls. Cache them first.
2. System prompt — your agent’s identity and rules. Stable across a session. (If you are still tuning yours, see how to write a system prompt for Claude.)
3. Long context / examples / RAG documents — the big static payload, if you have one.
4. The cache_control marker goes on the last block you want cached.
5. The actual user turn — the one thing that changes every call — goes after the marker, uncached.

Get this backwards and you cache nothing. If a per-request timestamp or a freshly shuffled tool list sits before your breakpoint, the prefix is no longer byte-identical and every call is a cache miss. I have debugged this exact failure more than once — a hidden dynamic value poisoning an otherwise perfect prefix. It belongs in the same family of bugs as the silent failures that never throw an error, they just quietly cost you money.

You get up to four cache breakpoints per request, so you can cache tools and system prompt separately from a large document block and still have everything reused.

Claude prompt caching tutorial: the actual code

Here is the minimal change. This is a stripped version of what runs in my cron job — the same shape, real SDK, Python.

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = open("system_prompt.md").read()   # ~28K tokens, stable

resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},   # <-- the breakpoint
        }
    ],
    messages=[
        {"role": "user", "content": user_turn}        # the only thing that changes
    ],
)

usage = resp.usage
print(usage.cache_creation_input_tokens)  # >0 on the write
print(usage.cache_read_input_tokens)      # >0 on every hit

The entire change is the cache_control block in the system array. That is it. The first call returns a non-zero cache_creation_input_tokens — you paid the write premium. Every call after it, inside the window, returns a non-zero cache_read_input_tokens and a near-zero creation count. If cache_read_input_tokens stays at zero across repeated calls, your cache is not working — stop and check your prefix before you ship.

For tool-heavy agents, mark the last tool definition instead, or in addition. The 1M-context beta on Claude Opus 4.7 makes caching more valuable, not less — the bigger the static context you carry, the more the 10% read rate saves you.

One constraint to respect: the cached block has to clear a minimum length or Anthropic ignores the marker. That floor is 1,024 tokens for Opus and Sonnet and 2,048 for Haiku 4.5. A 300-token system prompt will not cache no matter how you mark it. This rarely bites real agents, whose system prompts are already large, but it explains why a toy example sometimes shows no savings.

The TTL: 5 minutes, and what refreshes it

The cache is ephemeral. The default time-to-live is 5 minutes, and — this is the part people miss — the clock resets on every hit. As long as you keep reading the cache at least once every five minutes, it stays warm indefinitely. A chat session with a user typing every 30 seconds keeps the cache alive the whole conversation for the price of one write.

Anthropic also offers a 1-hour TTL for a steeper write premium. The decision is purely about your traffic gaps:

• Calls less than 5 minutes apart → default 5-minute TTL. Free to refresh, costs nothing extra.
• Calls 5 to 60 minutes apart → 1-hour TTL can be worth the higher write cost, since you avoid re-writing the whole prefix on every wake-up.
• Calls hours apart → caching does not help; the cache expires between runs and every call pays a write.

My 200-call cron job runs in tight bursts, so the 5-minute default carries it — the first call of a burst writes, the rest read. A pipeline that fires once an hour would either eat a write every time or move to the 1-hour TTL. Knowing your call cadence is the whole decision, which is one more reason to instrument cost per call before you tune anything in production deployment.

The real before-and-after numbers

Here is the math on the actual job, no rounding for flattery. The stable prefix is 30,000 tokens. The job runs 200 times a day on Opus 4.7.

Before caching: every call processes 30,000 input tokens at $5 per million.

• Per call: 30,000 × $5 / 1,000,000 = $0.15
• Per day: $0.15 × 200 = $30
• Per month: roughly $900, for the prefix alone

After caching, assuming the burst pattern produces about 20 cache writes a day and 180 reads:

• Writes: 20 × 30,000 × $6.25 / 1,000,000 = $3.75
• Reads: 180 × 30,000 × $0.50 / 1,000,000 = $2.70
• Per day: about $6.45
• Per month: roughly $194

That is a 78% cut on that job once you count the write premium honestly. The headline “90%” is the rate on a pure cache read — $0.015 versus $0.15 per call — and that is what you hit on the read-dominated jobs, the ones that fire in tight loops all day. The more often you reuse the prefix, the closer your real number gets to the 90% rate, because the one-time write cost amortizes toward nothing.

Output tokens are never cached and never discounted — caching only touches the input side. So the savings scale with how much static context you carry, not how much the model writes back.

Wiring caching into an n8n pipeline

Most of my agent traffic does not call the SDK directly — it runs through n8n workflows. The caching change is the same idea, just expressed in the HTTP Request node’s JSON body instead of Python. You set the system field as an array of content blocks and attach cache_control to the static one.

{
  "model": "claude-opus-4-7",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "{{ $json.system_prompt }}",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "{{ $json.user_turn }}" }
  ]
}

The trap in n8n specifically: if you build the system prompt by interpolating an expression that includes anything per-run — a {{ $now }} timestamp, an execution ID, a counter — the prefix changes every execution and you cache nothing while believing you do. Keep the cached block built from static data files only, and push the per-run variables into the messages array where they belong. Then log cache_read_input_tokens from the response into a sheet so you can prove the cache is hitting instead of assuming it. Verifying the response field rather than trusting the config is the same discipline that keeps the rest of the pipeline honest.

Want ACRID to build this?

If you would rather have a working autonomous agent than spend the next month wiring one yourself, ACRID builds them as a service. Start with a free architect call or go straight to hire.