Claude Message Threads API: How to Use It, Limits and Pricing

On November 2, 2026, Anthropic put message threads for the Claude Messages API into public beta. The server now keeps your conversation between turns, so each later request sends only the new messages plus the id of the last response.

For long agent sessions this means smaller requests and a faster first token, and Claude Code already uses it by default for most users.

What Are Message Threads?

The Claude Messages API has always been stateless. Every request had to carry the full conversation: the system prompt, the tool definitions and every earlier user and assistant message. For a quick chat that is fine.

For a coding agent that makes hundreds of calls in one session, it means sending a huge payload again and again.

Message threads change that. You send the full conversation once, together with system and tools. The API stores the conversation on the server for a short time.

On each later turn you send only what is new, such as a fresh user message or a batch of tool_result blocks, plus the id of the previous response.

Anthropic’s own summary is short: “send your conversation once, and the API receives only what’s new with every turn.” The stored thread is kept in memory, encrypted under a server-managed key, and never written to durable storage.

One important detail: Claude still reads the full conversation on every turn. The request you upload is smaller, but the model’s input processing is not reduced. That is why token usage and price stay the same. The win is speed and smaller network payloads, not a lower bill.

Claude Code and the 35% Speed Gain

Claude Code is the best example of a workload that benefits. A long session keeps adding file reads, tool results and edits to the conversation. Once a session reaches hundreds of thousands of tokens, the time to first token (TTFT) grows.

According to Anthropic’s announcement, message threads are on by default for most Claude Code users. With that default, requests with 500K to 1M tokens see the median TTFT drop by about 35%. You do not need to change anything to get this in Claude Code. It happens behind the scenes.

Keep the numbers in context. The 35% figure is a median for very large requests. Short sessions with a few thousand tokens will see a much smaller change, because there was little history to resend in the first place.

If you want to keep long sessions lean anyway, the Claude Code commands cheat sheet covers /compact and /clear.

How to Use Message Threads (Step by Step)

Here is the full flow for your own app. It works with any model on the Claude API, since the docs say the beta is available on every model.

1. Update your SDK to a recent version that exposes client.beta.messages with the thread parameter.
2. Add the beta header anthropic-beta: message-threads-2026-08-12. In the Python SDK, pass betas=["message-threads-2026-08-12"]. You must send it on every request of the thread.
3. On the first turn, send the full conversation with system, tools and thread={"type": "create"}.
4. Save the response id. This identifies the stored thread.
5. On the next turn, send only the new message (or tool results) with thread={"type": "continue", "previous_message_id": "<last id>"}. Leave out system and tools.
6. Keep the same model, thinking, tool_choice and other fixed fields on every turn.
7. Keep your own full copy of the conversation in your app. You will need it to replay if the thread expires.
8. If a continue request returns 404 thread_not_found, send the full conversation again in a new create request.

Code Examples

This Python example is the raw pattern from Anthropic’s docs. Turn 1 creates the thread. Turn 2 continues it.

import anthropic

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"],
)

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

The Python SDK also has a helper that tracks the ids for you. Creating the helper sends no request. Each send() call creates or continues the thread as needed.

import anthropic

client = anthropic.Anthropic()

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.",
)

thread.send({"role": "user", "content": "Hi! I have a question about an order."})
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)

If you call the HTTP API directly, the same fields go in the JSON body. Here is a continue request with curl. Replace the id with the one from your last response.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "thread": {"type": "continue", "previous_message_id": "msg_YOUR_LAST_ID"},
    "messages": [
      {"role": "user", "content": "How long does standard shipping usually take?"}
    ]
  }'

For an agent loop, the continue request usually carries a user message with tool_result blocks. If a response ends with stop_reason: "pause_turn", continue with "messages": [] and do not add a new user message while it is paused.

Request Rules: Create-Only, Fixed and Free Fields

Threads are strict about which fields can change. The docs group them into three sets.

A few more rules matter in practice:

• Threads are append-only. Each response id can be continued once, and you must always continue from the latest one.
• To edit an old message or branch the conversation, start a new thread.
• If you use fallbacks, send them on every request of the thread or on none.
• Do not re-send old messages on a continue request. That can duplicate them or cause an error.

Expiry, Replay and Streaming

A thread expires 5 minutes after its last request. Each stored response restarts that 5-minute clock. The API deletes the stored data no more than 1 hour after its last use.

Note: No response tells you whether a turn was stored. You only find out on the next continue request. If it returns 404 thread_not_found, replay: send the full conversation (from your own copy) in a new create request, then carry on.

With streaming, the response id arrives in the message_start event, but you should continue only after message_stop. If you continue too early, you can get a 404. If the stream drops before message_stop, send the same continue request again. If that returns thread_already_continued or thread_continue_in_flight, replay with a create request.

Two other cases need care. If Claude refuses (stop_reason: "refusal"), do not continue. Start a new thread without the refused turn. If a fallback model wrote a turn, the API does not store it. Check usage.iterations for a fallback_message entry and replay if you see one.

Pricing, Limits and Availability

Message threads cost nothing extra. Anthropic’s announcement and the docs both say standard token rates and existing rate limits apply. You pay for the full conversation as input on each turn, the same as before. See the Claude API pricing guide for the per-model rates.

Message Threads vs Prompt Caching

These two features solve different problems, and you will often use both together.

Prompt caching lowers cost and processing time for the repeated prefix of your prompt. On Claude, a 5-minute cache write costs 1.25x the base input price and a cache read costs 0.1x (0.05x on Opus 5.5 and Sonnet 5.5). You still send the full prompt each time. My prompt caching guide covers it in depth.

Message threads lower the size of each upload. You stop resending the history. But a thread does not cache automatically.

If you want the discount, you must add cache_control yourself. The simplest way is a top-level cache_control: {"type": "ephemeral"} on every request, which caches the last cacheable block of each request’s messages. That is exactly what the docs examples do.

The short version: use caching to save money, add threads to save time on long sessions. Breakpoints you set on system, tools or earlier messages persist across turns and cannot be moved later, and breakpoints on the create request count again on every continue, so plan your four breakpoints up front.

When Not to Use Message Threads

Threads are a great fit for coding agents, computer use agents with many screenshots, and document-heavy chats. They are a poor fit in these cases:

• Short chats. If the conversation is only a few turns and a few thousand tokens, there is little to gain.
• Slow, human-paced chats. If users often pause more than 5 minutes, threads keep expiring and you pay the replay cost anyway.
• Message Batches. Not supported. The batch item ends with invalid_request_error.
• Token counting. Not supported. Count the full conversation instead.
• Compaction and context editing. Threads are append-only, so server-side compaction is not supported. Context editing works only for clear_thinking_20251015 with keep: "all".
• Branching or editing history. You cannot rewrite old turns. Apps with “edit and regenerate” buttons need a new thread for each branch.
• Regulated data. Threads are not ZDR or HIPAA eligible, and organizations with HIPAA readiness or Inference hooks turned on cannot use them.
• Changing tools mid-session. Tools are fixed at create time. If your agent swaps tool sets often, you will start many threads.

My Take

This is a practical, low-risk feature. It costs nothing extra, it does not change your rate limits, and the fallback path is simple: if anything breaks, send the full conversation like you always did. The fact that Claude Code already runs on it tells me Anthropic trusts it for heavy daily use.

Tip: The catch is the strict rules. Fixed fields, append-only history and the 5-minute idle window mean you should wrap threads in a small helper that always keeps a full local copy and replays on any 404.

If you build agents, add threads on top of prompt caching. If you build a simple chatbot, you can skip it for now. If you compare agent tools, my Cursor vs Windsurf vs Claude Code vs Cline post may also help.

Troubleshooting: Common Errors and Fixes

400 with no error_code. You probably sent system or tools on a continue request, or forgot previous_message_id. Remove them or add the id.

“a maximum of 4 blocks with cache_control”. You have too many breakpoints. Remember the top-level one counts, and create-request breakpoints count again on every continue.

Thinking blocks rejected after changing system or tools. On Fable 5.1, Mythos 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5, changing system or tools invalidates old thinking blocks. Omit them from the new create request.

429 or 529 errors. These are not thread errors. Threads do not change rate limits. See how to fix Claude API 429 and 529 errors.

Frequently Asked Questions

Do message threads make the Claude API cheaper?

No. Standard token rates apply, and Claude still reads the full conversation on every turn. To lower cost, combine threads with prompt caching by adding cache_control.

How long does a message thread last?

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

Do I need to change anything in Claude Code?

No. Anthropic says message threads are on by default for most Claude Code users, and that is where the roughly 35% median TTFT drop for 500K to 1M token requests comes from.

Which models support message threads?

The docs say the beta is available on every model. It runs on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Claude in Microsoft Foundry.

Can I edit or delete a stored thread?

No. There is no API to list, read or delete threads, and threads are append-only. To branch or edit, start a new thread with a create request.

Can I use message threads with the Batch API?

No. Message Batches are not supported, and token counting returns a 400 error when thread is set.

Is my conversation data stored on disk?

According to Anthropic, threads are held in memory, encrypted under a server-managed key and never written to durable storage. They are still not ZDR or HIPAA eligible.

Sources

• Claude Platform release notes (November 2, 2026 entry)
• Message threads, Claude Platform Docs
• Make long-running agents faster with message threads, Claude blog
• Claude API pricing, Claude Platform Docs
• ClaudeDevs announcement on X