Claude API message threads beta cuts request size for long agent loops

1 hour ago

9 min read

Anthropic has added message threads, a beta feature of the Claude Messages API that keeps a conversation on Anthropic's servers for a short time so that each new request carries only the latest messages instead of the entire history. The feature appeared in the Claude Platform release notes on November 2, 2026, and is switched on with the beta header `message-threads-2026-08-12`, which has to be sent on every request that belongs to a thread.

According to the release notes, the goal is smaller requests and a lower time to first token for long conversations and agent loops. The documentation adds that latency should stay lower and steadier as a conversation grows, which is the situation of coding agents and tool-using assistants that accumulate dozens of turns, long tool outputs and large system prompts. A stored thread expires five minutes after its last request and is deleted no more than one hour after its last use.

Message threads are available on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Claude in Microsoft Foundry. Anthropic's documentation states that threads change neither pricing nor rate limits, and that the feature is in beta on every model without publishing a separate list of supported models.

··········

HOW CLAUDE API MESSAGE THREADS WORK.

A thread starts with an ordinary Messages API request that contains the full conversation, the `system` prompt and the `tools`, plus one extra parameter: `"thread": {"type": "create"}`. The API answers with a normal message and stores the conversation, including Claude's reply, under that response's `id`.

Every following turn sends only what is new, usually a `user` message or a set of `tool_result` blocks, together with `"thread": {"type": "continue", "previous_message_id": "<previous id>"}`. The `system` prompt and the tools are left out because the thread already holds them. Each response produces a new `id`, and the next turn must continue from that latest identifier.

Threads are append-only. A given response `id` can be continued once, so editing an earlier turn or branching a conversation requires starting a new thread. The API also does not compare the new messages with what it has stored, which means that a message sent twice can appear twice in the conversation or trigger an error. Anthropic is explicit that storage is best-effort: the application must keep its own complete copy of every message, because no response confirms that a turn was stored, and the only signal arrives on the next continue request.

Each stored response restarts the five-minute expiry clock. When a thread has expired or cannot be continued for another reason, the continue request fails and the client is expected to replay the full conversation in a new create request.

··········

CLAUDE API MESSAGE THREADS: REQUEST FIELDS ON CREATE AND CONTINUE.

The documentation splits request fields into three groups, and most integration mistakes will come from mixing them up. Fields fixed at creation must keep identical values on every turn; the API stores a fingerprint of them and rejects any change.

........

Group	Fields	Rule on continue requests
Create-only	system, tools	Never sent again; even null returns a 400
Fixed	model, tool_choice, thinking, mcp_servers, context_management, output_config, container skills, top-level cache_control, anthropic-beta values	Same values every turn, otherwise thread_fingerprint_mismatch
Free	max_tokens, stop_sequences, stream, metadata, service_tier and fields not listed	Can change on each turn

........

There are a few exceptions inside the fixed group. The API does not store MCP server URLs, MCP authorization tokens or the container `id`, so `mcp_servers` and `container` have to be sent on every request that uses them. Changing any create-only or fixed field means opening a new thread.

For the current Claude models with extended thinking (Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 and Claude Haiku 5.5), the documentation warns that changing `system` or `tools` invalidates earlier `thinking` and `redacted_thinking` blocks, and a create request that still contains them can return a 400. Leaving those blocks out of a replayed conversation avoids the problem.

The official Python example below shows the raw two-step pattern without the SDK helper.

client = anthropic.Anthropic()

# Turn 1: send the full conversation and create a thread
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
    messages=[{"role": "user", "content": "Hi! I have a question about an order."}],
    thread={"type": "create"},
    betas=["message-threads-2026-08-12"],
)

# Turn 2: send only the new message and the id of the turn 1 response.
# Leave out system and tools: the thread keeps them.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    messages=[
        {"role": "user", "content": "How long does standard shipping usually take?"}
    ],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

The SDK also offers a helper, `client.beta.messages.thread(...)`, that adds the beta header, decides between create and continue, replays the conversation once after the recoverable errors, resumes `pause_turn` responses and handles refusals by discarding the refused turn. Its copy of the conversation lives only in memory, and it does not retry a dropped stream by itself. Anthropic's tool runner uses a thread by default unless it is called with `thread=False`.

··········

WHAT MESSAGE THREADS CHANGE IN REQUEST SIZE FOR A CLAUDE AGENT LOOP.

The practical gain is easiest to see with numbers. The example below is illustrative and uses assumptions chosen by Data Studios, not figures from Anthropic: an agent loop of 30 turns, a system prompt plus tool definitions of 8,000 tokens, 1,500 tokens of new input per turn (a user message or tool results) and 500 tokens of model output per turn. Without a thread, every request resends the system prompt, the tools and all earlier turns. With a thread, only the first request carries the full context.

........

Measure (illustrative 30-turn loop)	Without thread	With message threads
Tokens sent on turn 1	9,500	9,500
Tokens sent on turn 30	67,500	1,500
Tokens sent across all 30 turns	1,155,000	53,000
Ratio of tokens uploaded	21.8x	1x

........

Under these assumptions the client uploads about 22 times less conversation data over the session, and the last request is 45 times smaller than its full-history equivalent. That reduction concerns what travels over the network and what the API must receive and parse before the model starts. Anthropic's documentation says that threads do not change pricing or rate limits, and it does not describe any discount on input tokens, so the saving to expect from this beta is in request size and latency, while the token bill follows the existing pricing and caching rules.

··········

PROMPT CACHING WITH CLAUDE API MESSAGE THREADS.

Threads do not cache anything automatically. Caching works as it does without a thread, and the developer still decides where breakpoints go. The recommended pattern is a top-level `cache_control` sent on every request: the API applies it to the last cacheable block of each request's messages, so each turn reads the earlier conversation from cache and writes the new turn.

The constraint to plan for is the breakpoint limit. A thread request can carry at most four `cache_control` breakpoints, the top-level one counts as one, and breakpoints placed on the create request's `system` and `tools` are counted again on every continue request. Exceeding the limit returns a 400 with `thread_unsupported_request`. Breakpoints cannot be moved or removed once sent.

The timing of threads matches the default cache. Anthropic's prompt caching documentation gives the standard cache a five-minute lifetime, refreshed at no cost each time it is used, with an optional one-hour lifetime at a higher write price (2 times the base input price instead of 1.25 times). Cache reads cost 0.1 times the base input price on most models and 0.05 times on Claude Opus 5.5 and Claude Sonnet 5.5. A thread that stays active keeps both its server-side state and its cache warm; a thread idle for more than five minutes has to be replayed, and the replay will usually start with a cache write.

··········

CLAUDE API MESSAGE THREADS ERRORS AND RECOVERY STEPS.

All thread errors are returned before the model runs, so a failed request consumes no tokens and does not change the thread's expiry.

........

Status	error_code	Meaning	What to do
404	thread_not_found	Thread cannot be continued	Replay full conversation in a new create request
400	thread_fingerprint_mismatch	A fixed field changed	Restore the field or start a new thread
400	thread_already_continued	That response id was already continued	Continue from the latest id or replay
400	thread_continue_in_flight	Another continue from that id is running	Wait, or replay
400	thread_unsupported_request	Unsupported feature or setting	Remove it or send without thread

........

The 404 does not explain its cause. The documentation lists several possibilities: the thread expired; the previous turn was served but not stored, for example a tool call cut off by `max_tokens`; a fallback model wrote the previous response; the previous response is still generating; the request comes from a different organization, workspace, user or service account; or the new messages add something the stored conversation cannot take, such as the first image in a text-only conversation. Developers should check `error.details.error_code` before replaying, because a request for a nonexistent model also returns a 404. If a replayed conversation still returns 404, it may be too large to store and should be sent without `thread`.

Streaming needs one extra rule. The response `id` arrives in `message_start`, but a continue request must wait for `message_stop`. If a continue stream drops before completion, the client resends the same request, and replays in a new thread if the API answers with `thread_already_continued` or `thread_continue_in_flight`.

A refusal ends the thread. When `stop_reason` is `"refusal"`, the API may already hold the refused turn, so the documentation tells developers to start a new thread without that turn or with it rephrased. Server-side fallbacks work on the Claude API, but `fallbacks` must be sent on every request or on none, and a response written by a fallback model is not stored; the client detects it through a `fallback_message` entry in `usage.iterations` and replays.

··········

WHO CAN USE CLAUDE API MESSAGE THREADS AND WHAT IS EXCLUDED.

The documentation lists no plan requirement or waitlist for the beta on the four platforms, and it states that prices and rate limits stay the same. The exclusions are mostly about compliance and batch workloads, and they decide whether the feature fits a given production setup.

........

Area	Status in the message threads beta
Platforms	Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Microsoft Foundry
Pricing and rate limits	Unchanged
Message Batches	Not supported; batch items with thread fail
Token counting	Not supported; count the full conversation instead
Compaction and context editing	Not supported, except clear_thinking with keep all
Zero data retention	Not eligible
HIPAA readiness and inference hooks	Not eligible
Thread management API	None; threads cannot be listed, read or deleted

........

On storage, Anthropic says the API holds a thread in memory, encrypted under a server-managed key, never writes it to durable storage and deletes it no more than one hour after last use. The stored contents are the conversation sent to the model, the create request's `system` and `tools` and a fingerprint of the fixed fields. Files are held by reference, so every file a conversation uses must remain available while the thread is in use. Using threads does not affect the eligibility of other features for zero data retention.

Teams that want a broader view of the Messages API, its endpoints and authentication options can start from our guide to Claude API integration, endpoints and structured outputs. The threads beta arrives a few days after Anthropic raised the request size limit, covered in our report on the Claude API 128 MB request limit and the usage and cost analytics API, and after the deprecation of fast mode for Claude Opus 4.8, which pushes fast-mode users toward Claude Opus 5.5.

For a developer deciding whether to adopt the beta, the steps are concrete. Add the `message-threads-2026-08-12` header to every request in the conversation; send `system`, `tools` and the full history only on the create request; keep fixed fields identical on every turn; keep a complete local copy of the conversation; handle `thread_not_found` with a full replay; and leave threads off for batch jobs, token counting, HIPAA workloads and organizations that rely on zero data retention.

··········

CLAUDE API MESSAGE THREADS: CONFIRMED FACTS AND OPEN QUESTIONS.

The documented facts are clear. Message threads are a beta of the Messages API, enabled by the `message-threads-2026-08-12` header, announced in the Claude Platform release notes on November 2, 2026 and available on the Claude API, AWS, Google Cloud and Microsoft Foundry. A thread expires five minutes after its last request and is deleted within one hour, prices and rate limits do not change, and the feature is excluded from zero data retention, HIPAA-ready organizations, batches, token counting and compaction.

Several points remain undisclosed. Anthropic has not published measured latency gains, so the claim of a lower and steadier time to first token is the company's own description without figures. The documentation does not state the maximum conversation size a thread can store, only that very large conversations may fail to be stored. There is no published timeline for general availability, for a longer expiry window or for a thread management API.

The design choices show where the feature fits. Because storage is best-effort and the client must always be able to replay, message threads work as a transport optimization for active, fast-moving sessions such as coding agents and tool loops, while the application keeps full ownership of the conversation record. For long-running agents that already make heavy use of prompt caching, the change lies in smaller uploads and simpler continue requests; the token cost of each turn stays governed by the existing pricing and cache rules.

··········

·····

DATA STUDIOS

·····

datastudios.org