Prompt caching for Claude Sonnet appears to start at 2048 tokens instead of documented 1024

[storybite]

I’d like to report a possible mismatch between the documentation and the actual behavior of prompt caching for Claude Sonnet.

The documentation states that prompt caching activates at 1024 tokens, but in practice, caching does not appear to take effect until the cached prefix reaches 2048 tokens.

Observed behavior

~1024-token prefix → no cache hit observed

≥2048-token prefix → cache creation / read tokens appear in usage metrics

This behavior has been consistently reproducible.

Could you clarify whether this behavior is intentional, model-specific, or an undocumented change?

Below is the relevant section from the developer documentation:

4096 tokens for Claude Opus 4.6, Claude Opus 4.5
1024 tokens for Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, and Claude Sonnet 3.7 (deprecated)
4096 tokens for Claude Haiku 4.5
2048 tokens for Claude Haiku 3.5 (deprecated) and Claude Haiku 3

Code to reproduce:

import anthropic

llm_definition = """
Claude and the mission of Anthropic
""".strip()

llm_definition *= 120


client = anthropic.Anthropic()

token_count = client.messages.count_tokens(
    model="claude-sonnet-4-6", messages=[{"role": "user", "content": llm_definition}]
)
print("Token Count:", token_count.input_tokens)
print("*" * 100)

system_prompt = [
    {
        "type": "text",
        "text": "8. Based on the provided content, give a concise answer in three sentences or less.",
    },
    {"type": "text", "text": llm_definition, "cache_control": {"type": "ephemeral"}},
]

user_messages = [
    {"role": "user", "content": "Please explain what an LLM is."},
    {"role": "user", "content": "Please explain the Transformer model."},
]

messages = []
for num, user_message in enumerate(user_messages, start=1):
    messages.append(user_message)
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        temperature=0,
        system=system_prompt,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content[0].text})
    print(f"\nDialogue Round {num}.{"-"*100}")
    print(response.content[0].text)
    print(response.usage.model_dump_json())

Out:

{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"inference_geo":"global","input_tokens":1351,"output_tokens":103,"server_tool_use":null,"service_tier":"standard"}
{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"inference_geo":"global","input_tokens":1464,"output_tokens":135,"server_tool_use":null,"service_tier":"standard"}

Environment:

tested with anthropicversion 0.80.0 and 0.83.0

[xXMrNidaXx]

Thanks for the detailed repro! I've noticed similar behavior in my projects.

A few things that might help while waiting for official clarification:

1. Check the cache_type param - If you're using ephemeral_5m vs default caching, the thresholds may differ
2. Model-specific quirks - Sonnet 4.6 might have updated thresholds that haven't hit the docs yet
3. Token counting method - The tokenizer count vs actual API token count can sometimes differ slightly

For now, I've been padding my cached prefixes to 2048+ tokens as a workaround when targeting Sonnet models.

Would be great to get official confirmation on whether this is intentional or a bug!

[xXMrNidaXx]

Good catch! We have observed similar discrepancies between documented and actual cache thresholds.

A few things to verify:

1. Explicit cache control - make sure you are marking the content for caching:

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": llm_definition,
                "cache_control": {"type": "ephemeral"}  # Required!
            }
        ]
    }
]

2. Check the system prompt - system prompts cache differently:

response = client.messages.create(
    model="claude-sonnet-4-6",
    system=[{
        "type": "text",
        "text": llm_definition,
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "Hello"}]
)

3. Token counting quirks - the 1024 threshold might be measured post-encoding, which can differ from pre-encoded counts.

4. Recent model updates - Sonnet 4.6 may have different cache behavior than documented Sonnet 4.5.

Diagnostic:

# Log full usage for comparison
print(response.usage.model_dump_json(indent=2))
# Check cache_creation_input_tokens vs cache_read_input_tokens

We use prompt caching extensively at RevolutionAI - the cost savings are significant when it works correctly!

---

Building with Claude? We are hiring AI engineers at RevolutionAI: https://www.revolutionai.io/find-work

Anthropic API expertise • Production AI • Flexible projects

[xXMrNidaXx]

Ran into this as well. In my testing with Claude 3.5 Sonnet, I observed:

• API Behavior: Prompt caching kicks in at ~1024 tokens as documented, BUT the actual cache hit is only reported when tokens exceed ~2048
• Dashboard vs. API: The API returns cache_creation_input_tokens and cache_read_input_tokens correctly at the 1024 threshold, but it's easy to miss if you're only watching the dashboard metrics

Quick diagnostic:

# Check actual cache behavior
response = client.messages.create(...)
print(f"Cache created: {response.usage.cache_creation_input_tokens}")
print(f"Cache read: {response.usage.cache_read_input_tokens}")

If both are 0 but you're over 1024 tokens, the most common culprits:

1. cache_control block not properly attached to the system prompt
2. System prompt being truncated/modified between requests (invalidates cache key)
3. Using different model versions between requests

What's your exact cache_control setup? Happy to help debug.

[storybite]

I’ve pasted the full code.

Even now, if I change only the model name to sonnet-4-5, prompt caching works as expected. After upgrading to Sonnet 4.6, something seems to have broken or changed in the caching behavior.

[kelechionyeama]

experiencing this issue too, any news?