How do Claude message threads speed up long-running agents?

Message threads are a public beta feature of the Claude Messages API, announced on November 2, 2026, that keeps a conversation on Anthropic's servers between turns. Your agent sends the full conversation once, then only the new messages and the ID of the previous response. Anthropic says this lowers time to first token in long sessions, while token usage, pricing and rate limits stay the same ^[1][2].

What are Claude message threads?

A message thread is a short-lived server-side copy of a Messages API conversation that later requests can append to. You opt in with the thread request parameter and the beta header message-threads-2026-08-12, and the response is an ordinary message ^[2][3].

The problem it targets is the shape of agent loops. Without a thread, every turn uploads the whole conversation again, and the API validates and tokenizes all of it again ^[2]. The announcement notes that coding agents can make hundreds of requests per session, so a history of hundreds of thousands of tokens is resent many times ^[1].

Anthropic already runs the feature in its own product. Message threads are on by default for most Claude Code users, and for requests of 500k to 1M tokens, median time to first token dropped by about 35% ^[1].

How do message threads work?

A thread has three moves: create, continue and replay. The first request carries the full conversation, system and tools, plus "thread": {"type": "create"}, and the API stores the conversation, including Claude's reply, under the response id ^[2]. Each later request sends only the new messages with "thread": {"type": "continue", "previous_message_id": "<id>"} and leaves system and tools out.

Threads are best-effort. A thread expires 5 minutes after its last request, each stored response restarts that timer, and the API deletes the thread no more than 1 hour after its last use ^[2][3]. When the API cannot continue a thread, a continue request returns a 404 error, and you send the full conversation again in a new create request.

Claude still reads the full conversation on every turn, which is why token usage does not change ^[1]. The saving is in what travels over the wire and what the API has to reprocess before the model starts, not in billed tokens.

Which request fields can change between turns?

Fields fall into three groups, and getting them wrong is the most likely source of 400 errors ^[2].

The API does not store MCP server URLs, MCP authorization tokens or the container id, so you send mcp_servers and container on every request that uses them ^[2]. To change a create-only or fixed field, such as switching models mid-task, you start a new thread with the full conversation.

A thread is append-only, and each response id can be continued once ^[2]. Editing or branching an earlier message, or compacting history into a summary, means starting a new thread.

How do you use message threads from the SDK?

The SDK thread helper does most of the work: it adds the beta header, sends the full conversation on the first turn and only new messages after that ^[2]. This Python example follows the documentation:

import anthropic

client = anthropic.Anthropic()

# Creating the helper sends no request.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
)

# Turn 1 creates the thread with the full conversation.
thread.send({"role": "user", "content": "Hi, I have a question about an order."})

# Turn 2 continues it and sends only the new message.
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

for block in second.content:
    if block.type == "text":
        print(block.text)

The helper replays the full conversation once when a continue request returns thread_not_found, thread_already_continued or thread_continue_in_flight, resumes pause_turn responses, and starts a new thread after a refusal ^[2]. If you set unsupported_request_behavior to continue_unthreaded, it falls back to plain requests when the API cannot store the conversation. The SDK's beta tool runner also uses a thread by default, and you can turn that off when you create the runner.

If you build requests yourself, send the message-threads-2026-08-12 header on every request of the thread, and with streaming, continue only after the message_stop event, because an earlier continue request can return 404 ^[2].

Prompt caching still needs breakpoints

A thread does not cache your prompt for you ^[2]. To cache each turn, send the same top-level cache_control on every request, as in the example. A thread request can carry at most 4 cache_control breakpoints, and the top-level one counts as one; one too many returns 400 with thread_unsupported_request.

What does this mean for teams running AI agents?

For teams, message threads mostly change how quickly long-running agents respond, not what they cost. Anthropic names three workloads that benefit most: long-running coding agents, computer use agents whose screenshots stay with the thread instead of being re-uploaded, and document- or image-heavy workflows ^[1].

The engineering rule that matters most is that your application stays the source of truth. The documentation tells you to keep your own copy of every message and build the replay path from the start, because no response says whether the API stored that turn ^[2]. The SDK helper keeps its copy only in memory, so an agent whose conversation must survive a process restart, or move between workers, needs its own storage.

Ownership also matters when several services drive one agent. A continue request from a different organization, workspace, user or service account than the one that created the thread returns thread_not_found ^[2]. Use one API key and workspace for the whole thread, and on Claude Platform on AWS, the same IAM role or user.

Where is it available, and what does it not support?

Message threads are in beta on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Claude in Microsoft Foundry ^[2][3]. The documentation lists every current model as supported, from claude-sonnet-4-5-20250929 through claude-fable-5-1 and claude-mythos-5-1, including claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-5-5 ^[2].

Several features do not work with threads ^[2]:

• Message Batches and token counting (count the full conversation instead).
• Compaction, including compaction on demand, and context editing, except clear_thinking_20251015 with keep: "all".
• Organizations with HIPAA readiness or inference hooks turned on.

What are the limits and open questions?

The beta has no API to list, read or delete a thread ^[2]. The 404 for a thread that cannot be continued does not say why; causes include expiry, a turn the API served but did not store, a response written by a fallback model, and a first image added to a conversation that had none. On the Claude API, server-side fallback works with threads, although some organizations get a thread_unsupported_request error when they combine the two; a fallback model's turn is never stored, so with sticky routing an agent might send the full conversation on every turn ^[2].

The 35% figure comes from Claude Code at 500k to 1M tokens ^[1]. Anthropic has not published numbers for shorter conversations, so measure time to first token on your own traffic before you rely on a specific gain. The announcement and documentation also do not say when the feature will leave beta.