Claude message threads: build the replay path before you switch

Claude message threads, in beta on the Messages API, keep a conversation on Anthropic's servers briefly so each later turn sends only the new messages. Long agent loops get smaller requests and a lower time to first token. But a thread is not guaranteed to survive until the next turn, so your agent needs a tested replay path first.

What was released

Message threads were announced by Anthropic on 2 November 2026 in the Claude API release notes, behind the message-threads-2026-08-12 beta header. They work on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Claude in Microsoft Foundry. The message threads guide lists support for current models from Claude Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 back to Claude Sonnet 4.5 and Haiku 4.5.

Without a thread, every turn uploads the whole conversation again and the API validates and tokenises all of it. With a thread, most of that work covers only the new turn. Anthropic states that threads do not change pricing or rate limits.

How a thread changes each request

There is one new request field, thread, and the response is the usual message:

• Create. The first request carries the full conversation, system and tools, plus "thread": {"type": "create"}. The API stores the conversation, including Claude's reply, under the response id.
• Continue. Later requests send only the messages since the previous response, plus "thread": {"type": "continue", "previous_message_id": "<id>"}. Sending system or tools on a continue request, even as null, returns a 400 error.
• Fixed fields. model, tool_choice, thinking, mcp_servers, context_management, output_config, container skills, the top-level cache_control and the set of beta headers must match the create request on every turn. A difference returns thread_fingerprint_mismatch. Fields such as max_tokens, stream and metadata can change freely.
• Append-only. Each response id can be continued once. To edit or branch an earlier message, or to compact the conversation into a summary, you start a new thread.
• Expiry. A thread expires five minutes after its last request and is deleted no more than an hour after its last use. A continue request on a thread the API can no longer use returns a 404 with thread_not_found.

The SDKs include a thread helper that adds the beta header, sends only new messages, and replays the full conversation once when it gets thread_not_found. The SDK's beta tool runner uses a thread by default, which you can turn off when you create the runner.

What threads don't support

The guide lists features that threads don't support: Message Batches, token counting with a thread field, compaction and compaction on demand, most context editing, organisations with HIPAA readiness enabled, and organisations with Inference hooks turned on. A request can also carry at most 4 cache_control breakpoints, with the top-level one counting as one.

Threads are not eligible for Zero Data Retention. The API holds a thread in memory, encrypted under a server-managed key, and never writes it to durable storage, but a ZDR agreement does not cover it.

What it means for teams building agents on Claude

Build the replay path first. This is CodeDTX's advice, but it follows directly from the guide: the response to a create or continue request never says whether the API stored that turn, so you only find out on the next request. Keep your own full copy of every message, as you do today, and treat a 404 as normal rather than as an outage. Test it on purpose by waiting past the expiry window in a staging run, so the first replay doesn't happen in production.

Threads don't replace prompt caching. A thread does not cache anything for you. If your agent relies on cached prefixes for cost, as we described in controlling AI agent running costs, keep the top-level cache_control and send the same value on every turn. Count your breakpoints: an agent that already places several on system and tools can hit the limit once it moves to threads.

Check the fixed fields against how your agent works. Agents that switch models mid-run, change tool_choice per step or edit the tool list as a task progresses will hit thread_fingerprint_mismatch. Either keep those values stable or plan for a new thread at each change. If you rely on server-side fallbacks, a turn written by a fallback model is not stored, so the next turn replays the full conversation.

Decide on compaction. Agents that use compaction or context editing to stay inside the context window can't use them with threads. For those agents, compare the time-to-first-token gain with the work of writing your own summary and starting a new thread from it. The guidance on context engineering for AI agents still applies to what goes into that summary.

When not to switch. Leave threads off for batch jobs, for organisations with HIPAA readiness or Inference hooks, and for any workload whose data agreements depend on ZDR. Short conversations gain little, because the request is already small. The clearest fit is a long, interactive agent loop where users wait on each step, and where a slower turn after a replay is acceptable.

Frequently asked questions

Do Claude message threads cost less than normal requests?

No. Anthropic states that threads do not change pricing or rate limits. The gain is smaller requests and a lower, steadier time to first token in long conversations. Token costs still depend on prompt caching, which threads do not do for you. Send the same top-level cache_control on every turn if you want each turn cached, and keep within the limit on breakpoints per request.

What happens when a Claude message thread expires?

A continue request returns a 404 error with the code thread_not_found. Send the full conversation from your own copy in a new create request, with system and tools, then continue from the new response id. The SDK thread helper does this replay once by itself. The same error can appear for other reasons, such as a turn the API served but did not store, so always handle it.

Can I use message threads with Message Batches or compaction?

No. A batch item that includes thread ends with an invalid request error, and a threaded request that sets compaction or sends a compaction block returns a 400 error. Context editing is unsupported too, apart from clearing thinking blocks while keeping all of them. To shorten a threaded conversation, write the summary in your own code and start a new thread from it.

Are message threads covered by Zero Data Retention?

No. Message threads are not eligible for Zero Data Retention, though using them does not affect other features that are. The API keeps a thread in memory, encrypted under a server-managed key, never writes it to durable storage and deletes it no more than an hour after its last use. Teams whose contracts require ZDR for every request should leave threads off.