Claude API Message Threads: Smaller Requests for Long Chats and Agent Loops

Anthropic added message threads to the Claude API on November 2, 2026, as a beta. With a thread, the API keeps the conversation on its servers, so each later request sends only the new messages. Anthropic says that gives long conversations and agent loops smaller requests and a lower time to first token.

The catch is time. A thread expires 5 minutes after its last request, and Anthropic deletes it no more than 1 hour after its last use. This piece covers what shipped, how to create and continue a thread, who gains from it, what it does not support, and the data questions agencies should ask before turning it on for a client.

The short version: message threads help most when turns come quickly, such as an agent calling tools in a loop. They change nothing about price. Your code must keep its own copy of the conversation and resend it whenever a thread expires. Threads are not eligible for zero data retention or HIPAA, so check client contracts first.

What Anthropic shipped on November 2

Anthropic’s platform release notes list message threads under November 2, 2026. The feature uses the beta header message-threads-2026-08-12.

Amazon Bedrock is not on Anthropic’s platform list for this feature.

Why message threads cut request size

Without a thread, every turn of a conversation resends everything: the system prompt, the tool definitions and every earlier message. Anthropic’s message threads documentation says that without a thread, "every turn uploads the whole conversation again, and the API validates and tokenizes all of it again."

With a thread, you send the full conversation once. After that, you send only the new turn plus the ID of the last response. The API rebuilds the conversation on its side before calling the model.

The docs say time to first token "stays lower and steadier as the conversation grows." Anthropic gives no figures, so measure it on your own traffic. Our explainer on context windows covers why long conversations get slow and expensive in the first place.

How to create and continue a Claude API thread

You add one parameter, thread, to an ordinary Messages API request. There are two request types.

Create. Send the full conversation, with system and tools, plus "thread": {"type": "create"}. The API stores the conversation and Claude’s reply under the response id.

Continue. Send only the messages since the last response, plus "thread": {"type": "continue", "previous_message_id": "<id>"}. Leave out system and tools. Sending either on a continue request returns a 400 error, even as null.

Here is the continue step in Python, shortened from Anthropic’s example:

second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    messages=[{"role": "user", "content": "How long does shipping take?"}],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

Anthropic’s SDK also has a thread helper, client.beta.messages.thread(...). It adds the beta header, creates the thread on the first turn and continues it after that. It also replays the conversation once when a thread can no longer be continued.

Four rules trip people up:

• Fixed fields stay fixed. `model`, `tool_choice`, `thinking`, the top-level `cache_control` and the set of beta headers must match on every request. A change returns 400 with `thread_fingerprint_mismatch`.
• Each ID continues once. Always continue from the latest response ID. A thread is append-only, so editing or branching means a new thread.
• Wait for the end of a stream. The docs say to continue only after `message_stop`, or the request can return a 404.
• Use one key. A continue from a different workspace, user or service account than the creator returns a 404.

The 5-minute expiry, and the replay path you must build

Anthropic calls a thread "best-effort." It expires 5 minutes after its last request, and each stored response restarts the clock. After that, a continue request returns a 404 with the error code thread_not_found.

The fix is a replay. You send the full conversation again in a new create request, then continue from the new ID. That only works if your application kept every message. The docs say: "Your application stays the source of truth for the conversation."

The docs list other causes of thread_not_found besides expiry. A response cut off by max_tokens in the middle of a tool call may not be stored. A turn written by a fallback model is not stored either. No response tells you whether a turn was stored. You find out on the next continue request.

This shapes who gains. An agent that calls tools every few seconds stays inside the window for the whole job. A member-services chatbot where people read, take a call and come back 10 minutes later will hit the replay path often. Those replays cost about what a request without a thread costs, so nothing is lost, but little is gained.

Pricing and prompt caching with message threads

Anthropic’s docs say: "Threads do not change pricing or rate limits." The page does not say that earlier turns are billed differently, so plan your budget as if they are not. As we read it, the saving is in request size and response time, not in tokens billed.

Caching is still your lever for cost. A thread does not cache anything for you. To cache each turn, send a top-level cache_control on every request, and the API places it on the last cacheable block. Prompt caching has its own rates and its own 5-minute and 1-hour cache lifetimes, so plan the two together.

Two limits apply. A threaded request can carry at most 4 cache_control breakpoints, and the top-level one counts as one. Breakpoints on system and tools from the create request count again on every continue. Going over returns 400 with thread_unsupported_request.

What message threads do not support

The docs list features that do not work with a thread:

• Message Batches. A batch item with `thread` ends with an `invalid_request_error`.
• Token counting. Count the full conversation instead.
• Compaction and most context editing. To shorten a long thread, write a summary in your own code and start a new thread with it.
• Some organizations. Those with HIPAA readiness or Inference hooks turned on.

There is also no API to list, read or delete a thread. If a refusal ends a turn, Anthropic says not to continue that thread. Start a new one without the turn that caused it.

Data retention questions for message threads

Anthropic’s page 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 its last use. It holds the conversation, the system prompt, the tools and a fingerprint of the fixed fields. Files are held by reference.

That is short. It is still storage, and two labels on the page matter for client work: message threads are not eligible for zero data retention (ZDR), and not eligible for HIPAA. Anthropic says using threads does not affect your use of other ZDR-eligible features.

Questions to settle before turning message threads on for a client:

1. Does the contract require ZDR? If it covers all API data, threads do not qualify. Ask Anthropic how threads fit your ZDR agreement.
2. Is health or other regulated data in the prompts? Threads are not HIPAA eligible, and HIPAA-ready organizations cannot use them.
3. Where does your copy of the conversation live? The replay path means your app keeps a full transcript. Treat that store as client data.
4. Which files do you reference? Threads hold files by reference, so those files must stay available while the thread runs.
5. Is it in your data map? Add the 1-hour window to the client’s records, next to your normal API retention terms.

How OpenAI and Google handle stateful conversations

Both other large platforms already keep conversation state on the server, for much longer. OpenAI’s conversation state guide says the Responses API chains turns with previous_response_id, saves response objects for 30 days by default unless store is false, and bills all earlier input tokens in the chain again. Its Conversations API keeps items with no 30-day limit; we covered that move in our post on the Assistants API shutdown. Google’s Interactions API guide uses previous_interaction_id, stores interactions by default with store=true, and keeps them 55 days on the paid tier and 1 day on the free tier.

Who should use Claude API message threads

Good fits:

• Agent loops with many tool calls in a row, such as a site audit agent or a content migration script. Our posts on AI agents and Claude Managed Agents cover where those loops run.
• Long chats with quick back-and-forth, such as an internal research assistant.

Poor fits: batch jobs, one-shot requests like alt text or tagging, chats with long pauses, apps that edit or branch history, and any client that needs ZDR or HIPAA. If you change instructions mid-conversation, note that changing system starts a new thread. Our post on mid-conversation system messages covers a pattern that keeps the system prompt stable.

Start on staging. Keep your own transcript, build the replay path first, and compare time to first token with and without the thread parameter. The feature is a beta, so re-check Anthropic’s docs before you depend on it.

Frequently Asked Questions