Anthropic's Message Threads Stop You Resending the Whole Conversation. They Also Expire in 5 Minutes and Are Not ZDR-Eligible. Read the Fine Print Before You Switch.
Anthropic's Messages API has a beta feature called message threads, and the documentation for it is unusually blunt about what it will not do. The pitch is simple: keep the conversation on the server for a short time so each turn sends only the new messages. The fine print is that "short time" means five minutes, the thread can vanish at any point, and you still pay for the same tokens.
How it works
You add the beta header message-threads-2026-08-12 to every request in the thread. The first call sends the full conversation, the system prompt and the tools, with "thread": {"type": "create"}. The response id identifies the stored thread. Each later call sends "thread": {"type": "continue", "previous_message_id": "<id>"} plus only the new messages, usually a user message or tool results. system and tools are create-only. Send either on a continue request, even as null, and you get a 400.
Some fields must match the create request exactly, including model, tool_choice, thinking, mcp_servers and the beta header set. Change one and you get a thread_fingerprint_mismatch error. Things like max_tokens, stop_sequences, stream and metadata can change per turn. A thread is append-only, and each response id can be continued once, so you cannot branch from an earlier turn.
The limits that matter
A thread expires 5 minutes after its last request, and each stored response restarts that clock. The API deletes it no later than an hour after last use. The docs describe threads as best-effort: a continue request can return a 404 thread_not_found, and the instruction is to replay the full conversation in a new create request. There is no API to list, read or delete a thread.
The feature does not work with Message Batches, token counting, on-demand compaction, most context editing, or organizations with HIPAA readiness or inference hooks. It is not eligible for zero data retention. The docs say the thread is held in memory, encrypted under a server-managed key and never written to durable storage. Fallbacks need care too: if a response comes from a fallback model the API does not store that turn, so you replay. And after a refusal, you start a new thread.
What it does not do for your bill
The docs say threads do not change pricing or rate limits, and prompt caching still works as usual, which means a thread does not cache automatically. You add cache_control breakpoints yourself, up to 4 per thread request. A news aggregator quoted a median time-to-first-token drop of about 35% on requests of 500k to 1M tokens. The documentation I read gives no latency numbers, so I treat that figure as unconfirmed.
So the win is smaller request bodies and, per Anthropic, steadier time to first token in long loops. It is not a discount.
Where I think it fits
It makes sense for agent loops that run turn after turn without long pauses: a coding agent working through tool calls, a support bot mid-conversation. It makes less sense for a chat where users walk away for ten minutes, because every return trip becomes a replay. If your app already has to handle the replay, the thread is an optimization on top of a path you cannot remove.
That is the part I would plan for: your application must keep its own full copy of the conversation. The docs say so. A thread is a cache you cannot inspect, not a database.
Where this could be wrong
I have not benchmarked threads in a real loop, and request size is not always your bottleneck. For many apps the model's generation time dwarfs the cost of uploading a few hundred kilobytes of history. If you already use prompt caching well, the gain may be modest. The beta header is dated August 12, so this is not brand new, and behavior could shift before general availability.
What I'd actually do
I would wrap it in a small helper that does three things: try the continue call, catch a 404 thread_not_found, and replay the stored transcript with a fresh create call. I would write the test for that replay path first, because it will fire in production more often than you expect. Then I would measure time to first token on one real agent loop before rolling it out.
And I would not use it anywhere I had promised a customer zero data retention or HIPAA handling. That is a contract question, not a tuning one.
Author
Lukas
@lukcombinator