Claude message threads: send only the new turn, and keep your own copy anyway

Published November 3, 20264 min read

The feature sits behind the message-threads-2026-08-12 beta header, per the API release notes. Anthropic's launch article gives one number: “With message threads on by default for most Claude Code users, requests with 500k to 1M tokens see median TTFT drop by about 35%.”

That figure comes from Claude Code's traffic on very large contexts, so don't expect it on a 30K-token chat. We haven't measured threads ourselves. Everything below is from the message threads docs.

How it works

Without a thread, every turn of an agent loop uploads the whole conversation again, and the API validates and tokenizes all of it again. With a thread, you add one field to a normal Messages request:

// Turn 1: full conversation, system prompt, and tools
{ "model": "claude-opus-5-5", "system": "...", "tools": [...],
  "messages": [...], "thread": { "type": "create" } }

// Turn 2 onward: only the new messages, no system or tools
{ "model": "claude-opus-5-5",
  "messages": [ { "role": "user", "content": [ { "type": "tool_result", ... } ] } ],
  "thread": { "type": "continue", "previous_message_id": "msg_..." } }

Each response id becomes the previous_message_id for the next turn. Claude still reads the full conversation on every turn. Only the upload and the request processing get smaller. The Python SDK has a client.beta.messages.thread(...) helper that adds the header, tracks the ids, and keeps a copy of the conversation in memory.

What changes and what doesn't

The caching row is the one to get right. If you were relying on cache reads to keep agent costs down, a thread without cache_control loses them. The docs' own examples set cache_control: {"type": "ephemeral"} at the top level on every turn.

Build the replay path first

The docs are blunt: “A thread is best-effort. It expires 5 minutes after its last request.” There's no API to list, read, or delete a thread, and no response tells you whether a turn was stored. You find out on the next continue request, which returns a 404 with error.details.error_code: "thread_not_found".

The recovery is always the same: send the full conversation in a new create request and continue from that response. That means your application stays the source of truth. Keep every message, including tool results, exactly as you'd need to replay them. Check the error code before replaying, because an unknown model also returns a 404.

The five-minute window matters for agents that wait on people. An agent that pauses for a human approval, or runs a 10-minute test suite between turns, will usually come back to an expired thread. It still works through the replay, but that turn gets none of the latency benefit.

Gotchas for agent builders

• You can't switch models mid-thread. model, tool_choice, thinking, mcp_servers, context_management, output_config, top-level cache_control, and the set of beta headers must match on every request, or you get a 400 thread_fingerprint_mismatch. Routers that send easy turns to a cheaper model need a new thread per switch.
• Tools are fixed at creation. Sending system or tools on a continue request returns a 400, even as null. Agents that add tools dynamically have to start a new thread.
• No forking. Each response id can be continued once (thread_already_continued). If you branch a conversation for parallel subagents, give each branch its own create request.
• Compaction means a new thread. A thread is append-only. To summarize old turns, start a new thread from the summary. On-demand compaction requests return a 400.
• Streaming: the id arrives in message_start, but continue only after message_stop. If a stream drops, resend the same continue request, then replay if that fails.
• Fallbacks and refusals: a response from a server-side fallback model can't be continued, and after stop_reason: "refusal" you start a new thread without the refused turn.
• Not supported: Message Batches, token counting, and organizations with HIPAA readiness or inference hooks turned on.

Who should turn it on

If you use Claude Code, there's nothing to do. Anthropic says threads are already on by default for most users. If you build on the Agent SDK or a framework, check whether it supports threads before writing your own. We didn't find any framework announcements in the first day.

If you run your own loop on the Messages API, threads are a good fit when turns come quickly, contexts are large, and you keep the model and tool set fixed for a run. Skip them for batch jobs, workloads that need zero data retention, and loops that change models or tools every few turns.

For the other Claude API change that needs action this month, see our November 30 cutoffs guide. For recent Claude Code changes, see the Claude Code 2.1.311 guide.

Sources

• Claude API docs: Message threads: request fields, expiry, caching, errors, limits, and data handling.
• Anthropic: Message threads launch article (November 2, 2026): the Claude Code latency figure.
• Claude API release notes: November 2, 2026 entry.