Overview
Message threads are now in public beta on the Claude Platform. New in the Messages API, they let you send your conversation once, and the API receives only what’s new with every turn. That keeps time to first token (TTFT) lower and steadier as the conversation grows.
A coding agent might make hundreds of requests in one session, and once a conversation reaches hundreds of thousands of tokens, resending all of it adds time before Claude starts responding. Message threads are on by default for most Claude Code users, where requests with 500k to 1M tokens see median TTFT drop by about 35%.
Key features
-
Send only what’s new
Without a thread, 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. Your first request sends the full conversation with
systemandtoolsand adds thethreadparameter. Later requests send only the new messages and theidof the previous response.// First request "thread": {"type": "create"} // Later requests (leave out system and tools) "thread": {"type": "continue", "previous_message_id": "<previous id>"} -
SDK thread helper
The SDK has a thread helper that builds the thread requests for you. It creates a thread on the first turn, continues it after that, and adds the beta header. When a continue request returns
thread_not_foundor a similar error, it replays the full conversation once in a new create request. In Python, you create it withclient.beta.messages.thread(...)and send turns withthread.send(...). -
Built for active sessions
Message threads are best for active sessions where latency matters, including long-running coding agents, where each tool result or file edit adds to the conversation, computer use agents, where screenshots stay with the thread instead of being re-uploaded on every turn, and document- and image-heavy workflows.
-
Available on four platforms
The public beta covers the native Claude Platform, Claude Platform on AWS, Claude in Microsoft Foundry, and Claude Models on Google Cloud (Anthropic managed). If you build requests yourself, send the
message-threads-2026-08-12beta header on every request of a thread.
Notes
- Token usage doesn’t change — Claude still reads the full conversation on every turn, so token usage stays the same. Standard Claude token rates and existing rate limits apply.
- Prompt caching is still your call — A thread does not cache your prompt for you. To cache each turn, send a top-level
cache_controlon every request of the thread. A request withthreadcan carry at most 4cache_controlbreakpoints. - Threads are short-lived — A thread expires 5 minutes after its last request, and the API deletes it no more than 1 hour after its last use. If it can no longer be continued, a continue request returns a 404 error and you send the full conversation again. Your application stays the source of truth, so the docs recommend keeping your own copy of every message and building the replay path from the start.
- Some fields are fixed for the whole thread — Values such as
model,thinking,tool_choice, and the top-levelcache_controlmust match on every request. A thread is append-only, so to edit or branch an earlier message, start a new thread. - Unsupported features — Threads don’t support Message Batches, token counting, compaction, or context editing (with one
clear_thinking_20251015exception). Organizations with HIPAA readiness enabled or Inference hooks turned on can’t use them either. - Not ZDR eligible — A thread is held in memory, encrypted under a server-managed key, and never written to durable storage, but message threads are not eligible for Zero Data Retention (ZDR). Using this feature does not affect your use of other ZDR eligible features.
- Not the same as session threads — Message threads are different from session threads in Claude Managed Agents.
- Learn more — See the message threads docs for per-request field rules, error codes, and supported models.