◈AI Codex
Infrastructure & DeploymentHow It Works

Claude API message threads (beta): send only the new turn

In brief

Message threads let the Claude API hold a conversation on the server for a few minutes, so each turn you send only the new message. Requests get smaller and faster in long agent loops. Token costs stay the same, threads expire after 5 idle minutes, and they don't work with zero data retention.

4 min read·

Contents

♡Sign in to save

Short answer: with message threads (beta, since early November 2026), the Claude API keeps your conversation on its side for a short time. After the first request, you send only the new message plus the previous response's id. That makes requests smaller and faster in long agent loops. It doesn't cut token costs: Claude still reads the whole conversation each turn. A thread expires after 5 minutes without a request, and it isn't available with zero data retention.

Source: Anthropic's message threads docs.

How does it work?

  1. Create: send a normal request with the full conversation, system prompt and tools, plus "thread": {"type": "create"}.
  2. Continue: next turn, send only the new messages plus "thread": {"type": "continue", "previous_message_id": "<id from the last response>"}. Leave out system and tools.

Add the beta header anthropic-beta: message-threads-2026-08-12 to every request.

first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    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"],
)

second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "How long does standard shipping take?"}],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

The Python SDK also has a helper, client.beta.messages.thread(...), that creates and continues the thread for you.

The rules that trip people up

  • Expiry: a thread expires 5 minutes after its last request and is deleted within an hour. After that, a continue returns 404 thread_not_found. Start a new thread by resending the full conversation.
  • Keep your own copy. Your app is still the source of truth. You need the full history to recover from an expired thread.
  • Some fields are fixed. model, thinking, tool_choice, top-level cache_control and the beta headers must match the create request, or you get thread_fingerprint_mismatch. max_tokens, stream and metadata can change per turn.
  • Append-only. You can't edit or branch earlier turns. Each response id can be continued once. To change history, start a new thread.
  • Streaming: continue only after message_stop, even though the id arrives in message_start.
  • Caching isn't automatic. Add top-level cache_control on every request if you want each turn cached, as you would without threads.
  • Not with zero data retention. Thread contents sit in memory (encrypted, never written to disk) for up to an hour, so ZDR organizations can't use them.

Where is it available?

In beta on the Claude API, Claude Platform on AWS, Claude models on Google Cloud (Anthropic-managed) and Microsoft Foundry.

When should I use it?

  • Use it for long agent loops, coding agents, computer use agents that send screenshots every step, and chats with big documents. Anthropic and early coverage report noticeably faster first tokens on very long requests.
  • Skip it if you need zero data retention, if users go idle for long stretches (you'll keep re-creating threads), or if you often rewrite earlier turns.

Want lower costs, not just faster requests? That's prompt caching and the other levers in cutting Claude API costs.

Quick answers

What are message threads in the Claude API? A beta feature where the API holds a conversation on the server for a short time, so each turn you send only the new message and the previous response id instead of the full history.

Do message threads reduce Claude API costs? No. Requests are smaller and faster, but Claude still reads the whole conversation each turn, so token usage is the same. Use prompt caching to cut cost.

How long does a Claude message thread last? It expires 5 minutes after its last request and is deleted within an hour. After that, start a new thread with the full conversation.

Can I use message threads with zero data retention? No. Threads aren't eligible for zero data retention, though using them doesn't affect your other ZDR features.

Related tools

Weekly brief

For people actually using Claude at work.

Each week: one thing Claude can do in your work that most people haven't figured out yet — plus the failure modes to avoid. No tutorials. No hype.

No spam. Unsubscribe anytime.

What to read next

Picked for where you are now

All articles →