Say your agent is on turn 40. Every call still ships the previous 39 turns, the system prompt and every tool definition, and the API validates and tokenizes all of it again before the model starts. The longer the run, the longer you wait for the first token. On November 2, Anthropic's API release notes added message threads, a beta in which the first request carries the full conversation, the server keeps it, and each later request carries only the new messages plus the id of the previous response. The message threads documentation says this keeps time to first token lower and steadier as a conversation grows, and that long agent loops gain the most.
Two things should shape whether you adopt it. Threads do not change pricing or rate limits, so the saving is latency, not money. And the feature stores your conversation on Anthropic's side for a while, which is a real cost if your organization runs under zero data retention.
Create once, then continue from the last response id
If you write requests by hand, every request in a thread needs the anthropic-beta header message-threads-2026-08-12. The first one looks like any other Messages call, with the full messages, system and tools, plus "thread": {"type": "create"}. The API stores the conversation and Claude's reply under that response's id. After that you send only what is new, such as the user's next question or the tool_result for the last tool_use, with "thread": {"type": "continue"} and previous_message_id set to the id of the last response.
System and tools are the trap. They belong to the create request only, and sending either on a continue request returns a 400, even as null. A second group of fields is fixed for the life of the thread, and you resend each one on every turn with the value it had at create time. The ones you'll hit most are model, tool_choice and thinking. The top-level cache_control, output_config and the set of beta headers are fixed too, along with mcp_servers and a few others. Change any of them and the API returns thread_fingerprint_mismatch, naming the mismatched fields in the message. Fields like max_tokens, stream and service_tier can change every turn. Switching models or editing the system prompt means starting a new thread.
The SDK helper handles most of this. Message thread support landed in the Python SDK v2.2.0 and the TypeScript SDK sdk-v1.2.0 on October 23. You create a helper with client.beta.messages.thread(...) and call send() each turn; it adds the beta header, drops system and tools on continues, and replays the full conversation when a thread is gone. One line in the docs deserves more attention than it gets: the SDK's beta tool runner uses a thread by default unless you turn it off when you create the runner. The retention section below explains why that matters.
Your copy of the conversation is the real one
Anthropic describes threads as best effort. A thread expires 5 minutes after its last request, each stored response restarts that clock, and the contents are deleted no more than an hour after last use. Neither a create nor a continue response tells you whether the turn was actually stored. You find out on the next continue.
When a thread can't be continued, the API returns a 404 with thread_not_found and no reason. The documented causes range widely: the thread expired; the last turn ended in a tool call cut off by max_tokens and was never stored; a fallback model wrote it; it was still generating; the request came from a different organization or workspace; the request came from a different user or service account than the one that created the thread, and a thread created with a legacy workspace key stays with that key; or the new messages added something the stored conversation can't take, such as the first image in a text-only conversation. The documented recovery is to replay your full conversation, with system and tools, in a new create request. There are exceptions: after a turn written by a fallback model you can also start a new thread on that fallback model, and if a continue still returns a 404 right after a replay, the conversation may be too large to store, so send it without thread. When streaming, the id arrives in message_start, but wait for message_stop before continuing, because a continue sent earlier can also return a 404.
Threads are append-only, and each response id can be continued once. Editing an earlier message, branching, or recovering from a refusal all mean a new thread. That is why the docs insist your application keeps the full conversation and has a replay path from day one. If your agent regularly pauses for human approval longer than 5 minutes, most resumes will be replays, and the latency gain disappears.
The model sees the same context, and you have fewer ways to trim it
A thread saves upload and preprocessing; it doesn't shorten what the model reads. The API rebuilds the whole conversation before calling the model, and the context window fills exactly as before.
Because threads are append-only, you can't drop or compress earlier turns mid-thread. Compaction on demand, which entered beta in September, isn't available with threads, and a threaded request that sets the compaction parameter returns a 400. Context editing is out too, except clear_thinking_20251015 with keep: "all". Token counting and Message Batches reject requests that include thread, so count the full conversation instead. To slim a long conversation, write the summary in your own code and send it as an ordinary message in a new create request.
There is a knock-on effect on Claude Fable 5.1, Mythos 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5. Changing system or tools invalidates the thinking blocks already in the conversation, and the new create request can fail with a 400. The documented workaround is to leave every thinking block out, at the price of the model losing its earlier reasoning.
Your bill comes down through caching, not threads
The model reads the full conversation and prices are unchanged, so enabling threads won't shrink your token bill on its own. The docs say plainly that a thread doesn't cache your prompt for you.
The simplest setup is a top-level "cache_control": {"type": "ephemeral"} on every request. It is a fixed field, so send the same value each turn, and each turn then reads the earlier conversation from cache and writes the new turn. On the pricing page, a 5-minute cache write costs 1.25 times the base input price and a hit costs 0.1 times, or 0.05 times on Opus 5.5 and Sonnet 5.5 and 0.025 times on Fable 5.1 and Mythos 5.1. Opus 5.5 input is $4 per million tokens, and a cache hit on it is $0.20. That is where the money on a long, repeatedly read conversation is saved.
If you place breakpoints by hand, watch the limit. A threaded request allows four cache_control breakpoints, the top-level one counts, and breakpoints you put on system and tools at create time count again on every continue; one too many returns thread_unsupported_request. Note also that a thread expires after 5 idle minutes and the default prompt cache also lives 5 minutes, so a long pause tends to cost you both at once. The thread errors listed in the docs come back before the model runs and use no tokens.
The retention cost lands on ZDR and HIPAA organizations
A thread holds the conversation sent to the model, the system prompt and tools from the create request, and a fingerprint of the fixed fields. According to the docs, that data lives only in memory, encrypted under a server-managed key, is never written to durable storage, and is deleted no more than an hour after the thread's last use. Files are held by reference, so they need to stay available while the thread is in use. There is no API to list, read or delete a thread, so you can't purge one early.
The API and data retention page marks message threads as eligible for neither ZDR nor HIPAA, and the two arrangements play out differently. Organizations with HIPAA readiness are blocked outright. Organizations with ZDR are not blocked: the same page says that using an ineligible feature is a choice to step outside your ZDR arrangement for that data, under the feature's own retention policy. Anthropic adds that using threads doesn't affect your other ZDR-eligible features.
The real risk is opting in without noticing, for example by upgrading the SDK and running the beta tool runner under a ZDR contract. For organizations without ZDR, the July 1 version of Anthropic's privacy center article says API inputs and outputs are deleted within 30 days by default, so an extra hour in memory changes little.
Some things the docs leave open. They don't say how the stored part of the conversation appears in usage on a continue request, only that pricing is unchanged; they don't put a number on a conversation too large to store; they give no date for the end of the beta; and the SDK release notes don't say which version made the tool runner thread by default. The supported platforms are the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Claude in Microsoft Foundry; Amazon Bedrock isn't on the list.
If your agent runs long conversations with turns a few seconds to a few tens of seconds apart and your organization has no ZDR contract, try the SDK helper with a top-level cache_control and track two numbers: time to first token and how often you replay. If you are under ZDR or HIPAA, search your code for thread and the tool runner before your next SDK upgrade, so the conversation doesn't leave your arrangement by default.
