{"id":468,"date":"2026-07-16T13:03:50","date_gmt":"2026-07-16T13:03:50","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/claude-prompt-caching-2026-the-setup-that-cut-my-api-bill\/"},"modified":"2026-07-16T13:03:50","modified_gmt":"2026-07-16T13:03:50","slug":"claude-prompt-caching-2026-the-setup-that-cut-my-api-bill","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/claude-prompt-caching-2026-the-setup-that-cut-my-api-bill\/","title":{"rendered":"Claude Prompt Caching in 2026: The Setup That Actually Cut My API Bill"},"content":{"rendered":"

Confession: I stared at last month’s Anthropic bill, made a small sad noise into my coffee, and then spent the rest of the morning re-reading the prompt caching docs<\/a> like they owed me money. Turns out, they kind of did.<\/p>\n

I’d been running a support-triage app on top of Claude for a while. Same 8k-token system prompt, same tool definitions, same handful of policy docs on every single request. I knew about cache_control<\/code>. I’d even added it once, six months ago, and then never checked whether it was actually doing anything. Spoiler: it wasn’t, because I’d put the breakpoint in the wrong spot and Anthropic had quietly changed the default TTL under me.<\/p>\n

This is the writeup I wish I’d read six months ago. What Claude prompt caching actually does, where I put cache_control<\/code> in real requests, the 5-minute vs 1-hour TTL choice, what broke when I got greedy, and the actual line-item difference on my bill.<\/p>\n

What prompt caching actually does (in one paragraph)<\/h2>\n

You mark a chunk of your prompt with cache_control<\/code>. If the same prefix shows up again within the TTL, Claude serves that portion from a warm cache instead of re-processing it. Cache reads are cheap: about 10% of the input token price. Cache writes cost more than a normal input token, though: roughly 1.25\u00d7 for the 5-minute TTL and 2\u00d7 for the 1-hour TTL. So caching only wins when you’ll read the cached block enough times to amortize the write.<\/p>\n

The rule of thumb I use, borrowed from Anthropic’s own guidance and confirmed by this dev.to writeup on the 2026 TTL shift<\/a>: three reads to break even on 5-minute, five reads to break even on 1-hour. Below that, don’t bother.<\/p>\n

Here’s a Python example using the SDK. Before:<\/p>\n

from anthropic import Anthropic\n\nclient = Anthropic()\n\nresponse = client.messages.create(\n    model="claude-sonnet-5",\n    max_tokens=1024,\n    system=BIG_SYSTEM_PROMPT,  # 6k tokens, same every call\n    messages=[{"role": "user", "content": user_msg}],\n)\n<\/code><\/pre>\n
And after, with a single cache breakpoint:<\/p>\n
response = client.messages.create(\n    model="claude-sonnet-5",\n    max_tokens=1024,\n    system=[\n        {\n            "type": "text",\n            "text": BIG_SYSTEM_PROMPT,\n            "cache_control": {"type": "ephemeral"},\n        }\n    ],\n    messages=[{"role": "user", "content": user_msg}],\n)\n<\/code><\/pre>\n
That’s the whole change. On the first request you pay a small write premium. On every subsequent request inside the TTL window, the system prompt is basically free.<\/p>\n
Where I actually put cache_control in real requests<\/h2>\n
The docs let you place up to four breakpoints in a single request. That flexibility is a trap if you don’t have a plan. Here’s the ordering I settled on, from most stable to least stable. Cache the stable stuff first, because a cache hit only counts if everything before the breakpoint also matches.<\/p>\n
    \n
  1. Tool definitions.<\/strong> Change once a week at most. Always cache.<\/li>\n
  2. System prompt.<\/strong> Change on deploys. Always cache.<\/li>\n
  3. Long context documents<\/strong> (policy docs, code snippets, retrieved chunks). Cache if the same doc is going to show up in the next few requests.<\/li>\n
  4. Multi-turn conversation history.<\/strong> Cache the last-but-one assistant turn if you’re doing multi-turn.<\/li>\n<\/ol>\n
    For a typical support-triage request, my breakpoints look like this:<\/p>\n
    response = client.messages.create(\n    model="claude-sonnet-5",\n    max_tokens=1024,\n    tools=[\n        # ... tool defs ...\n        {"cache_control": {"type": "ephemeral"}}\n    ],\n    system=[\n        {"type": "text", "text": SYSTEM_PROMPT,\n         "cache_control": {"type": "ephemeral"}},\n    ],\n    messages=[\n        {"role": "user", "content": [\n            {"type": "text", "text": POLICY_DOC,\n             "cache_control": {"type": "ephemeral"}},\n            {"type": "text", "text": user_msg},\n        ]},\n    ],\n)\n<\/code><\/pre>\n
    Three breakpoints, one slot in reserve. Anthropic’s tool-use-with-prompt-caching guide<\/a> has the pattern for cascading breakpoints across multi-turn tool loops if you need more sophistication than this.<\/p>\n
    TypeScript is almost identical, with the same shape:<\/p>\n
    const response = await client.messages.create({\n  model: "claude-sonnet-5",\n  max_tokens: 1024,\n  system: [\n    {\n      type: "text",\n      text: SYSTEM_PROMPT,\n      cache_control: { type: "ephemeral" },\n    },\n  ],\n  messages: [{ role: "user", content: userMsg }],\n});\n<\/code><\/pre>\n
    If you’re on the Vercel AI SDK, the providerOptions.anthropic.cacheControl<\/code> field maps to the same thing. I wrote up how I use that stack in my post on the Vercel AI SDK v5<\/a>.<\/p>\n
    The 5-minute vs 1-hour TTL choice<\/h2>\n
    The default TTL is 5 minutes. If your traffic is bursty, like a customer opening a chat and sending 10 messages in a minute, 5 minutes is fine. Cheap writes, hits come easy.<\/p>\n
    The 1-hour TTL costs about 2\u00d7 on writes but keeps the cache warm through longer gaps. You opt into it per breakpoint:<\/p>\n
    "cache_control": {"type": "ephemeral", "ttl": "1h"}\n<\/code><\/pre>\n
    I use 1-hour on:
    \n– Batch pipelines where I know I’ll hit the same system prompt every few minutes for an hour.
    \n– Long-running evals where each iteration takes 4-6 minutes and I don’t want a 5-minute window ticking down every time.
    \n– The tool definitions in my agent loops, which get called dozens of times over the course of a session but with unpredictable gaps.<\/p>\n
    I stick with 5-minute on:
    \n– Interactive chat where cache hits are basically guaranteed inside a session.
    \n– Anything where the “outer” prompt (tools + system) is small enough that a re-write is cheaper than paying the 1-hour premium.<\/p>\n
    One thing to watch: Anthropic changed the default TTL from 60 minutes to 5 minutes for Claude Code in early 2026, and it caused a lot of quiet cost regressions. If you have ENABLE_PROMPT_CACHING_1H=1<\/code> set anywhere in an old shell profile, know what it’s doing.<\/p>\n
    What broke when I got greedy<\/h2>\n
    Three anti-patterns I ran into, in escalating order of expensive:<\/p>\n
    Cache-busting user data in the wrong slot.<\/strong> I once concatenated the user’s timestamp into the system prompt “for context”. Every request had a unique system prompt, so every request was a cache miss with a write premium. My bill went up<\/em>. The fix is obvious in retrospect: keep dynamic data in the user message, not the system prompt.<\/p>\n
    Breakpoints on tiny blocks.<\/strong> I tried caching a 200-token instruction block and paid the write premium on every call. Anthropic requires a minimum block size (1024 tokens for Sonnet, 2048 for Opus) for caching to activate at all. Smaller blocks are silently ignored. If you’re not sure, log the cache_creation_input_tokens<\/code> and cache_read_input_tokens<\/code> fields on the response and check that they’re both non-zero over a window of requests.<\/p>\n
    Assuming workspace isolation matched my mental model.<\/strong> As of February 2026, caches are isolated per Anthropic workspace on the direct API, not per organization. If you have staging and production in the same org but different workspaces, they don’t share cache. That’s usually what you want, but I had a batch job that assumed the opposite and paid twice.<\/p>\n
    The actual line-item difference on my bill<\/h2>\n
    Numbers from one of my triage services, comparing April (no caching) to May (with caching landed mid-April) with roughly matched request volumes:<\/p>\n