What Anthropic shipped

On 2 November 2026, Anthropic added message threads to the Claude Messages API as a public beta. Builders opt in with the message-threads-2026-08-12 beta header. Once it's on, the server holds the running conversation, and each later request carries only the newest turn.

Anthropic has already tested the feature on its own product. Most Claude Code users have threads switched on by default, and the company reports that on requests with 500,000 to 1 million tokens of context, median time to first token (TTFT) dropped by about 35%. Anthropic also says the gain gets bigger as an agent carries more context. That figure comes from very large sessions, so a short support chat probably won't see anything like it.

The beta runs on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry. The supported model list covers the current 5.x family, including Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1, and goes back as far as Sonnet 4.5 and Haiku 4.5.

Why long agent sessions feel slow

The Messages API has always been stateless. Every call sends the whole conversation again, and before Claude writes a single token the API has to validate and tokenise all of it. Picture a coding agent that has opened dozens of files, run a test suite several times and collected screenshots along the way. By turn fifty it's uploading a huge payload just to add one tool result, and the wait before the reply grows each time.

Threads move that history to Anthropic's side. Since the client sends only the new user message or tool_result blocks, the upload stays small and the preprocessing covers only the fresh material. The result is a wait before the first token that stays lower and more even as the session grows.

How a thread runs, call by call

A thread starts with a normal request containing the full conversation, the system prompt and the tools, plus "thread": {"type": "create"}. The API stores the exchange, including Claude's reply, under that response's id.

Each following turn sends only the messages added since that reply, with "thread": {"type": "continue", "previous_message_id": "<id>"}. These calls must leave out system and tools altogether. Sending them, even set to null, gets a 400 error. Each new response id becomes the pointer for the next turn.

There are a few structural rules to keep in mind:

  • Threads only grow forward. A given response id can be continued once, so branching a conversation, rewriting an earlier turn or changing the system prompt all mean starting a new thread.
  • The API doesn't spot duplicates. If your code resends a message by mistake, it'll show up twice in the stored history.
  • Some settings are locked at creation: model, tool_choice, thinking, mcp_servers (auth tokens aside), context_management, output_config, container skills, top-level cache_control and the beta headers. If any of these differ on a later turn, the API returns thread_fingerprint_mismatch and names the fields that changed.
  • Other settings can vary freely between turns: max_tokens, stop_sequences, stream, metadata and service_tier.

The replay path is part of the design

Anthropic calls threads best-effort, and that's the part builders most need to plan around. A thread goes idle and expires after five minutes without a request, though every stored reply restarts that clock. The data is deleted no more than an hour after last use.

When a continue call can't be served, the API sends back a 404 with thread_not_found and doesn't explain the cause. The docs list several possibilities:

  • the five-minute window ran out;
  • the previous reply went out but wasn't stored, for example a tool call cut short by max_tokens;
  • a fallback model produced the last reply, and threads stay tied to a single model;
  • the request came from a different API key, workspace or IAM identity;
  • the new turn brought in something the stored copy can't take, like the first image in a conversation that was text only until then.

The fix is the same each time. Send the complete history again as a fresh create request, then carry on from the new id. So your app has to keep its own full transcript, because the server copy can vanish without warning.

Streaming has its own rules. The response id arrives in message_start, but you should wait for message_stop before continuing, or you may hit a 404. If a stream drops, retry the same continue request. If that comes back with thread_already_continued or thread_continue_in_flight, do a full replay, which the docs describe as always safe. After a refusal stop reason, don't continue the thread. Open a new one that leaves out the turn that triggered it.

Costs, caching and token counts

Prices and rate limits haven't changed. Claude still reads the whole conversation on every turn, so input token usage stays where it was. The savings show up in latency, from smaller uploads and less preprocessing, and won't appear on your invoice.

Threads don't switch on prompt caching for you. To cache, you send the same top-level cache_control with every request. Each thread request can hold at most four cache breakpoints. That count includes the top-level one and any set on the create call's system and tools, and those count on every turn. Adding a fifth returns thread_unsupported_request. When you replay, it's worth stripping per-message breakpoints first so the fresh create call stays under the cap.

What doesn't work with threads yet

The beta leaves out a fair amount:

  • Message Batches and token counting. To count tokens, count the full conversation yourself.
  • Compaction, including the on-demand compaction beta Anthropic released in September.
  • Context editing, apart from clear_thinking_20251015 with keep: "all".
  • Organisations that have HIPAA readiness or inference hooks turned on.
  • Zero data retention. Threads aren't ZDR-eligible. Anthropic says contents stay in memory under a server-managed encryption key and never go to durable storage, but teams with strict retention policies should talk to their compliance people first.
  • Thread management. There's no endpoint to list, inspect or delete threads.
  • Files. These are held by reference, so they must stay available for as long as the thread is in use.

What builders can do now

The quickest route in is the SDK helper, client.beta.messages.thread(...), which ships in the Python, TypeScript, Go, Java, C#, PHP and Ruby SDKs. It adds the beta header, leaves system and tools off continue calls, replays once when a thread has gone missing, handles pause_turn, and opens a fresh thread after a refusal or a reply from a fallback model. The beta tool runner uses threads by default, and you can turn that off when you create the runner. Setting unsupported_request_behavior: "continue_unthreaded" lets the helper drop back to plain requests when the API rejects a thread or can't store a very large conversation.

The helper has gaps. It won't retry dropped streams, and fingerprint and unsupported-request errors still reach your code, so test those paths on purpose.

Here's what we'd do before turning threads on in production:

  • Benchmark your own sessions. Measure TTFT on your longest real runs with and without threads. The 35% figure is for half a million tokens and up.
  • Map your idle gaps. An agent that waits on human sign-off for more than five minutes will land on the replay path often, so make that path cheap and well tested.
  • Do your own compaction. Since built-in compaction is off the table, summarise older turns in your own code and start a new thread from the summary.
  • Pin one identity per thread. Keep the same API key and workspace for the whole conversation to avoid ownership 404s.

For agents that carry hundreds of thousands of tokens, threads look like an easy latency win. They just work best when the app treats the server copy as a cache it can rebuild at any time.

Sources

Build with people working on the same things

Join the Auckland Society for AI: NZ$599 a year with a ForgeBox and the members' projects area. Our Auckland meetups are open to everyone.

Become a member