Claude message threads on the Messages API: a thread saves the upload, only the cache saves the prefill

On November 2 Anthropic put message threads into beta on the Messages API, behind the message-threads-2026-08-12 header. The first request sends the whole conversation with "thread": {"type": "create"}. Every later request sends only the new messages plus the previous response id, and the API rebuilds the rest on its side. It runs on the Claude API, Claude Platform on AWS, Claude in Microsoft Foundry and Claude Models on Google Cloud (Anthropic managed), per the release notes.

The pitch is speed for long agent loops. Read the docs next to the prompt caching page, though, and a thread turns out to remove one cost and leave the other to the cache. Prefill is the larger of the two, and a thread never touches it.

What do Claude message threads actually make faster?

The shipping, not the reading. Without a thread, the docs say, every turn uploads the whole conversation again, and the API validates and tokenizes all of it again. With a thread, most of that work covers only the new turn. The model still reads everything: Anthropic’s announcement says token usage stays the same, and pricing and rate limits don’t change.

So the win scales with how much you resend. A coding agent at 800K tokens that adds a 2K tool result was shipping the full 800K to say 2K of new things. The announcement gives one measured number:

With message threads on by default for most Claude Code users, requests with
500k to 1M tokens see median TTFT drop by about 35%.

That is a median, on Claude Code traffic, in the top band of context size. My read of why it shows up there: Claude Code caches its prompt prefix, so with prefill already cheap, moving the conversation is a big share of the wait that is left. Nobody published a number for a 50K conversation. There is far less to resend, so there is less to save, but how much less is unmeasured. The Claude Code CHANGELOG, up to 2.1.317, doesn’t mention threads at all, so “on by default” is Anthropic’s word from the announcement, not a release note you can pin to a version.

Does a Claude message thread cache the prompt?

No, and the docs say it in one sentence: a thread does not cache your prompt for you. Prefill, the model processing the conversation before the first token, is what the prompt cache lets you skip, and you still place the breakpoints. The simple route is a top-level cache_control on every request.

That field is one of the fixed ones. model, thinking, tool_choice, output_config, the set of beta headers and the top-level cache_control must match the create request on every turn, or the API returns thread_fingerprint_mismatch. system and tools go on the create request only. Changing any of them means a new thread.

The breakpoint limit is the usual 4, with less room to move. Breakpoints on the create request’s system and tools count again on every continue, and a breakpoint can’t be moved or removed once sent. If you replay by hand, strip the old message breakpoints first; the SDK helper does that for you.

That gives two independent clocks. The thread expires 5 minutes after its last request. The cache lives 5 minutes by default, or an hour with ttl: "1h" at a higher write price (in Claude Code, only some sessions get the hour). On the hour TTL, a 20-minute pause kills the thread and can leave the cache warm, so the replay re-uploads everything and still reads the prefix cheaply, as long as the prefix and settings match. A lost thread announces itself: the next continue returns 404. A lost cache is silent, and cache diagnostics is how you tell an expired entry from a prompt you changed.

What do Claude message threads not support?

Most of the tools you use to manage a long conversation:

append-only        each response id can be continued once; no edits, no branches
5-minute expiry    then a continue returns 404 thread_not_found
no compaction      compaction on demand returns 400; summarize in your code, start a new thread
no context editing except clear_thinking_20251015 with keep: "all"
no token counting  count the full conversation with system and tools instead
no batches         a batch item with thread fails with invalid_request_error
not ZDR eligible   held in memory, deleted no more than 1 hour after last use

Organizations with HIPAA readiness or inference hooks can’t use threads at all. And no response tells you whether the API stored that turn; you find out on the next continue. So your app keeps every message. Every thread ends in a replay once it sits idle for five minutes, so build that path on day one and test it like the main one.

Does the Anthropic SDK turn Claude message threads on by default?

In the tool runner, yes. I read the anthropic 2.4.0 Python wheel. A tool runner threads its requests unless you pass thread=False, and it sets unsupported_request_behavior="continue_unthreaded": after a thread_unsupported_request error, or a second thread_not_found right after a replay, it drops the thread and sends full requests. Other errors still reach your code. The client attribute that allows threading, _supports_message_threads, is true on Anthropic and AsyncAnthropic, which the AWS and Foundry clients inherit. The Bedrock and Vertex clients have it false, and client.beta.messages.thread() raises there. If you run a tool-runner agent on data you promised to keep out of non-ZDR features, put thread=False in the same change that upgrades the SDK.

Should you build on Claude message threads now?

Turn it on where latency hurts and the context is huge: big coding loops, computer use with screenshots that otherwise go up every turn. Agents that wait on a human, a review or a timer outlive five minutes, so for them replay is the normal path and the thread pays off only inside bursts of work.

My advice for day one: before you add thread, log three numbers per request: context size, time to first token and cache_read_input_tokens. The announcement measured one cohort, and yours may not be in it. If cache reads are low, the cache is where your prefill time goes, and a thread won’t buy it back.