prompt-caching-patterns

Prompt Caching Patterns

Cache repeated prefixes when reuse offsets write costs. Cache eligibility and pricing depend on the model and platform; a short system prompt is not cached merely because it repeats.

Dated cache reference (2026-10-08)

Model	Minimum eligible prefix	Cache read / base input price
Claude Opus 5.5	512 tokens	5%
Claude Fable 5.1	512 tokens	2.5%
Claude Sonnet 5.5	512 tokens	5%
Claude Haiku 5.5	512 tokens	10%

For the Claude API, a five-minute write costs 1.25 times base input and a one-hour write costs 2 times base input. Recheck current pricing before budgeting; provider-specific billing and model availability can differ.

Prefix design

Cache order is tools → system → messages, regardless of the order of request keys. An explicit breakpoint includes the marked block and everything before it. Keep dynamic material after the stable prefix.

[ tool definitions              ] breakpoint 1
[ reusable system instructions  ] breakpoint 2
[ reference documents           ] breakpoint 3
[ stable conversation prefix    ] breakpoint 4
[ current variable content      ]

There are at most four breakpoints. Top-level automatic cache_control moves a breakpoint to the last eligible block and consumes one slot. Explicit markers give control over a static prefix.

Explicit caching example

The caller supplies the approved model, text and output limit. Marking a prefix below its model's minimum silently produces no cache entry.

def cached_answer(client, model, policy, document, question, max_tokens):
    return client.messages.create(
        model=model,
        max_tokens=max_tokens,
        system=[{
            "type": "text",
            "text": policy,
            "cache_control": {"type": "ephemeral"},
        }],
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": document,
                 "cache_control": {"type": "ephemeral"}},
                {"type": "text", "text": question},
            ],
        }],
    )