Anthropic wordmark logo in black letters on a white background, maker of Claude and the Claude message threads API feature

Claude Message Threads: Power-User Guide to Faster Agent Turns on the API

by

Last updated: November 3, 2026

Claude message threads are a new public beta in the Claude Messages API. You send the full conversation once with a thread parameter, then each later turn sends only new messages plus the previous response id. Anthropic reports about 35% lower median time to first token on 500k to 1M token requests.

Contents

Anthropic added the feature on November 2, 2026, according to the Claude Platform release notes, and explained it in the announcement Make long-running agents faster with message threads. It needs the beta header message-threads-2026-08-12.

Without a thread, every agent turn uploads, validates and tokenizes the whole conversation again. With a thread, most of that work covers only the new turn.

What changed at a glance

Item Detail
Status Public beta, header message-threads-2026-08-12
New parameter "thread": {"type": "create"} or "thread": {"type": "continue", "previous_message_id": "..."}
Platforms Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude in Microsoft Foundry
Models Opus 5.5, Sonnet 5.5, Haiku 5.5, Mythos 5.1, Fable 5.1 and earlier models back to Sonnet 4.5 and Haiku 4.5
Lifetime Expires 5 minutes after the last request; deleted no more than 1 hour after last use
Price and rate limits Unchanged; standard token rates apply
Reported gain About 35% lower median time to first token for 500k to 1M token requests in Claude Code

The 35% figure comes from Claude Code, where threads are on by default for most users. It is Anthropic’s own measurement.

How a thread works

The message threads documentation describes three steps:

  • Create. Send the first request as usual, with the full conversation, system and tools, and add "thread": {"type": "create"}. The API stores the conversation, including Claude’s reply, under the response id.
  • Continue. Send only the messages since the previous response and the previous id. Leave system and tools out; the thread keeps them.
  • Replay. A thread is best-effort. If the API can no longer continue it, you get a 404 error and send the full conversation again in a new create request.

Your application stays the source of truth. Keep your own copy of every message and build the replay path from the start, because no response tells you whether the API stored that turn.

How to turn it on

The quickest route is the SDK thread helper, which exists for Python, TypeScript, C#, Go, Java, PHP and Ruby.

  1. Update to an Anthropic SDK version that includes client.beta.messages.thread(...).
  2. Create the helper with the same fields as a Messages request, for example model, max_tokens, system and an optional top-level cache_control. Creating it sends no request.
  3. Call thread.send(...) with the first user message. The helper adds the beta header and creates the thread.
  4. Call send() for each later turn, passing only the new user message or tool_result blocks. The helper continues the thread and replays once on its own after a thread_not_found error.
  5. If you build requests yourself, add the anthropic-beta: message-threads-2026-08-12 header and the thread field to every request, and continue from each new response id.

The SDK beta tool runner also uses a thread by default, which you can turn off when you create the runner. Other helper methods include thread.fork() to copy a conversation, thread.append(...) to stage messages and thread.stream(...) to stream a turn. If you run agents in Claude Code, you may already be using threads.

What to send on each request

Group Fields Rule
Create-only system, tools Send on the create request only. Sending either on a continue request, even as null, returns a 400 error.
Fixed model, tool_choice, thinking, mcp_servers, context_management, output_config, top-level cache_control, beta headers Same value on every request, or a 400 thread_fingerprint_mismatch error.
Free max_tokens, stop_sequences, stream, metadata, service_tier Can change from turn to turn.

To change a create-only or fixed field, such as switching models, start a new thread. A thread is append-only and each response id can be continued once. On a pause_turn stop, continue with an empty messages list. After a refusal, do not continue: start a new thread without the turn that caused it.

Prompt caching and streaming

A thread does not cache your prompt for you. Prompt caching works as before, so send the same top-level cache_control on every request to cache each turn. A request with thread can carry at most 4 cache breakpoints, and the top-level one counts. One too many returns a 400 thread_unsupported_request error.

Caching is still what lowers input cost; see our Claude API pricing guide for current rates. When streaming, the response id arrives in message_start, but continue only after message_stop, or the request can return a 404.

Errors and recovery

These errors arrive before the model runs, so they use no tokens. thread_not_found (404) means replay the full conversation. thread_already_continued means continue from the latest id. thread_continue_in_flight means an earlier attempt is still running. thread_unsupported_request names a feature threads do not support.

A 404 can come from expiry, a different API key or workspace, a response written by a fallback model, or a response cut off mid tool call by max_tokens. Use the same key and workspace for the whole thread.

Threads compared with full replay

Aspect Without a thread With a thread
Request size Whole conversation every turn New messages only after the first turn
Time to first token Grows with the conversation Lower and steadier, per Anthropic
Token billing Full conversation read Same; full conversation still read
State Client only Client copy plus a short-lived server copy
Batches, token counting, compaction Supported Not supported with threads
Zero data retention Eligible where your org has it Not eligible

The best fits are long coding agents, computer use agents and document-heavy workflows. For a lighter model to pair with threads, see our Claude Haiku 5.5 guide. For other vendors’ agent APIs, compare the Perplexity Agent API and Microsoft Copilot Harness guides.

Limitations

  • There is no API to list, read or delete a thread.
  • Message Batches, token counting, compaction on demand and most context editing do not work with threads.
  • Organizations with HIPAA readiness or Inference hooks enabled cannot use threads.
  • On Opus 5.5, Sonnet 5.5, Haiku 5.5, Mythos 5.1 and Fable 5.1, changing system or tools can invalidate earlier thinking blocks; leave them out of a new thread.
  • Files are held by reference, so keep every file the conversation uses available while the thread is in use.

Frequently asked questions

What are Claude message threads?

Message threads are a public beta feature of the Claude Messages API, released November 2, 2026. The API keeps a conversation on the server for a short time, so each later request sends only the new messages and the id of the previous response instead of the whole history.

Do message threads lower my token costs?

No. Anthropic says threads do not change pricing or rate limits, and Claude still reads the full conversation on every turn, so token usage stays the same. The gain is smaller requests and a lower time to first token. Prompt caching is still how you cut input cost.

How long does a Claude message thread last?

A thread expires 5 minutes after its last request, and each stored response restarts that timer. The API deletes it no more than 1 hour after its last use. After that, a continue request returns a 404 thread_not_found error and you replay the full conversation.

Which models and platforms support message threads?

The beta covers current models including Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, Mythos 5.1 and Fable 5.1, plus older ones back to Sonnet 4.5. It runs on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Claude in Microsoft Foundry.

Are message threads eligible for zero data retention?

No. Threads are not ZDR eligible and not available to organizations with HIPAA readiness enabled. Anthropic says a thread is held in memory, encrypted under a server-managed key, never written to durable storage and deleted no more than 1 hour after last use.

Sources

Image: Anthropic logo, Wikimedia Commons, public domain (text logo below the threshold of originality), placed on a white background and resized. Anthropic and Claude are trademarks of Anthropic PBC. FreeAnswers is not affiliated with Anthropic.



Related answers

Leave a Comment