Claude API message threads: send only the new messages

Anthropic has released Claude API message threads in beta: the conversation stays on the server for a short while, and every follow-up request sends only the new messages. The feature landed in the Claude Release Notes on November 2 and works with the beta header message-threads-2026-08-12.

How do Claude API message threads work?

Until now, every turn of a conversation with the Messages API meant sending the whole history again: the system prompt, the tools and every message. According to the message threads documentation, the API had to validate and tokenize all of it each time. With a thread, most of that work covers only the new turn.

The whole mechanism is one new parameter, thread:

1. Send the first request as usual, with the full conversation, system and tools, plus "thread": {"type": "create"}. The API stores the conversation together with Claude’s response under that response’s id.
2. Follow-up requests carry "thread": {"type": "continue", "previous_message_id": "<id>"} and only the new messages, e.g. the next user message or tool results (tool_result).
3. Leave out system and tools, because the thread remembers them. Sending them in a continue request returns a 400 error.

Anthropic says the result is smaller requests and a shorter, more stable time to first token, even as the conversation grows. Long agent loops gain the most: the agent makes dozens of tool calls and used to resend an ever-growing history each time (more on how such loops work in what is an AI agent).

What does the SDK do for us?

The SDK has a new helper, client.beta.messages.thread(...). You create it with the same fields as a regular request, then send each following turn with thread.send(...). The helper adds the beta header itself, creates the thread on the first turn and continues it on the next ones.

Interestingly, the SDK’s beta tool runner uses threads by default, so agents built on it can get faster without any code changes (you can turn this off when creating the runner).

The helper also handles failure cases: when a thread expires, it resends the whole conversation in a new create request. It keeps that full copy of the conversation only in memory, though, for as long as the helper object exists.

What should you watch out for?

First, the short lifetime. A thread expires 5 minutes after the last request, and the API deletes it at most an hour after its last use. The documentation calls threads “best-effort”: your application must remain the source of truth for the conversation and handle resending everything after a 404 thread_not_found error from day one.

Second, what you must not change. Fields such as model, thinking, tool_choice and context_management must keep the same values for the whole thread, or the API returns a thread_fingerprint_mismatch error. A thread can only grow, and each response id can be continued once. To edit an earlier message or change the system prompt, start a new thread.

Third, prompt caching. A thread caches nothing on its own. Caching works as before, and a request with thread can hold at most 4 cache_control breakpoints. The simplest approach is to send the same top-level cache_control on every turn.

Fourth, the features threads don’t work with:

1. Message Batches and Token Counting.
2. Compaction, including on-demand compaction, and context editing (with one exception described in the documentation).
3. Organizations with HIPAA readiness or Inference hooks enabled.

Fifth, your data. Threads are not eligible for ZDR (zero data retention). According to the documentation, the conversation, the system prompt and the tools are kept in memory, encrypted with a server-managed key, and never written to persistent disk.

Where and with which models does it work?

Message threads are in beta on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (managed by Anthropic) and Microsoft Foundry. Supported models include Claude Fable 5.1 and Mythos 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5, and among older ones also Opus 4.5, Sonnet 4.5 and Haiku 4.5.

Threads don’t change pricing or rate limits. You pay for tokens as before, so the savings are in time and request size, and costs are still worth tracking, e.g. with the new Claude cost analytics API. It’s another change to the API itself in recent days, after the request size limit went up to 128 MB.

(Don’t confuse them with “session threads” in Claude Managed Agents. That’s a separate feature, as the documentation points out.)

FAQ

What are Claude API message threads?

A beta feature in which the API stores the conversation on the server for a short time. After the first request, you send only the new messages and the id of the previous response.

Do message threads lower Claude API costs?

Not directly. According to the documentation, threads don’t change pricing or rate limits. The gain is smaller requests and a shorter time to first token.

How long does the Claude API keep a thread?

A thread expires 5 minutes after the last request, and the API deletes it at most an hour after its last use. After that, you have to send the whole conversation again.

Do message threads work on Amazon Bedrock?

The documentation lists the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (managed by Anthropic) and Microsoft Foundry. Amazon Bedrock is not on the list.