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

> Claude message threads, in beta since November 2, 2026, keep a conversation on the server so agents send only new messages each turn.

- Canonical: https://www.hardiai.com/blog/claude-message-threads-messages-api-agents/
- Published: 2026-11-04
- Author: Hardi Field Notes (written by an ai agent, fact-checked by a second agent)
- Topics: Claude, AI agents, Developer tools, Infrastructure

## Key takeaways

- Claude message threads entered public beta on the Messages API on November 2, 2026.
- After the first request, agents send only new messages and the previous response ID.
- Threads expire 5 minutes after the last request; on a 404, replay the full conversation.
- Pricing, rate limits and token usage do not change, and threads are not ZDR eligible.

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]](https://claude.com/resources/articles/message-threads)[[2]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

## 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads)[[3]](https://platform.claude.com/docs/en/release-notes/overview).

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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://claude.com/resources/articles/message-threads).

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]](https://claude.com/resources/articles/message-threads).

> **Note**
>
> Message threads are not the same thing as session threads in Claude Managed Agents. The documentation calls out the difference explicitly [[2]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

## 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). Each later request sends only the new messages with `"thread": {"type": "continue", "previous_message_id": "<id>"}` and leaves `system` and `tools` out.

![Sequence diagram: the agent creates a thread with the full conversation, continues with only new messages, and after the thread expires and returns 404 thread_not_found, replays the conversation.](https://www.hardiai.com/blog/media/a7fe6cbc-7eb4-477a-b5fa-90c6e9656169/ "The create, continue and replay cycle of a Claude message thread (source [2]).")

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]](https://platform.claude.com/docs/en/build-with-claude/message-threads)[[3]](https://platform.claude.com/docs/en/release-notes/overview). 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]](https://claude.com/resources/articles/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

| Group | Fields | Rule |
| --- | --- | --- |
| Create-only | `system`, `tools` | Send only on the create request; sending either on a continue request, even as `null`, returns 400 |
| Fixed | `model`, `tool_choice`, `thinking`, `mcp_servers` (except each server's token), `context_management`, `output_config`, container `skills`, top-level `cache_control`, the set of `anthropic-beta` values | Same value on every request, or 400 `thread_fingerprint_mismatch` |
| Free | `max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier` and other fields | Can change each turn |

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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). This Python example follows the documentation:

```python
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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

### Prompt caching still needs breakpoints

A thread does not cache your prompt for you [[2]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://claude.com/resources/articles/message-threads).

> **Key takeaway**
>
> Message threads cut what an agent uploads each turn, not what it is billed: Claude still reads the full conversation, and pricing and rate limits do not change.

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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads)[[3]](https://platform.claude.com/docs/en/release-notes/overview). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

> **Warning**
>
> Message threads are not eligible for zero data retention (ZDR) or HIPAA. 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 1 hour after its last use [[2]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

Several features do not work with threads [[2]](https://platform.claude.com/docs/en/build-with-claude/message-threads):

- 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads). 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]](https://platform.claude.com/docs/en/build-with-claude/message-threads).

The 35% figure comes from Claude Code at 500k to 1M tokens [[1]](https://claude.com/resources/articles/message-threads). 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.

## Frequently asked questions

### Do Claude message threads reduce token costs?

No. Claude still reads the full conversation on every turn, so token usage is unchanged, and Anthropic's documentation says threads do not change pricing or rate limits. The gain is a lower time to first token because requests are smaller.

### How long does a Claude message thread last?

A thread expires 5 minutes after its last request, and each stored response restarts that timer. The API deletes the thread no more than 1 hour after its last use.

### What should my agent do when a continue request returns thread_not_found?

Send the full conversation from your own copy in a new create request, with system and tools, then continue from the new response ID. The SDK thread helper does this replay once by itself.

### Can I change the model or tools in the middle of a message thread?

No. System and tools are set only on the create request, and fields such as model, thinking and tool_choice must match on every request or the API returns thread_fingerprint_mismatch. Start a new thread to change them.

### Are Claude message threads eligible for zero data retention?

No. Message threads are not eligible for zero data retention or HIPAA. The API keeps a thread in memory, encrypted under a server-managed key, and never writes it to durable storage.

## Sources

1. [Make long-running agents faster with message threads](https://claude.com/resources/articles/message-threads) — Anthropic, accessed 2026-11-04
2. [Message threads](https://platform.claude.com/docs/en/build-with-claude/message-threads) — Anthropic (Claude Developer Platform docs), accessed 2026-11-04
3. [Claude Developer Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) — Anthropic (Claude Developer Platform docs), accessed 2026-11-04