Claude API Message Threads: What Changes for Long Agent Sessions

Claude API message threads let the Messages API hold a short-lived conversation on the server so each follow-up turn sends only the new messages instead of resending the entire history. Announced in public beta in early November 2026, the feature cuts request size and time to first token on long agent runs, though your billed token usage stays exactly the same.

If you have built a coding assistant or a multi-step tool loop, you know the pain of turn 40. Every time the model runs a command or inspects a screenshot, your client packs up every previous prompt, reply, and tool result and ships the whole bundle back over the wire. Message Threads is Anthropic’s fix for that transport and validation bottleneck—with a few strict rules around five-minute expirations, prompt caching, and data retention that you need to design for before turning it on.

What are Claude API message threads?

Message threads are a server-side conversation cache for the Claude Messages API, enabled in beta with the message-threads-2026-08-12 header. Instead of treating every API call as a blank slate that requires your full chat history, the server keeps the conversation in memory between turns so your client only transmits what changed since the last reply.

According to Anthropic’s November 2, 2026 release notes and documentation, this is separate from session threads in Claude Managed Agents. It works directly on /v1/messages across every model in beta, and it is available on the direct Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude in Microsoft Foundry.

Between turns, Anthropic holds the thread in server memory, encrypted under a server-managed key, and never writes it to durable disk storage.

What does Message Threads save — and what does it not?

Message Threads reduces network upload size and time to first token (TTFT) on long conversations, but it does not reduce your billed token count or change your rate limits.

When an agent session grows to hundreds of thousands of tokens—common when a coding loop reads large files or a computer-use agent passes screenshots back and forth—resending and validating that payload on every turn adds noticeable delay before the model even begins generating. Anthropic says that with message threads turned on by default for most Claude Code users, requests carrying 500k to 1M tokens see median TTFT drop by about 35%.

What it does not touch is your bill. Even though your HTTP request only contains the newest user message or tool output, Claude still reads the full conversation on every turn. Standard token rates apply: as of November 2026, Claude Opus 5.5 lists at $4 per million input tokens ($0.20 cached) and $20 per million output tokens, while Sonnet 5.5 runs $2 input ($0.10 cached) and $10 output (see our AI API pricing comparison and our Claude Opus 5.5 vs. Sonnet 5.5 guide for how those tiers stack up).

What changes with Message Threads	What stays the same
Smaller HTTP request payloads on follow-up turns	Full conversation tokens read and billed on every turn
Lower time to first token (~35% median TTFT drop on 500k–1M token requests in Claude Code, per Anthropic)	Standard API token pricing and existing rate limits
system and tools sent once when creating the thread	Your app remains the source of truth for message history

How do you create and continue a thread?

You start a thread by sending a normal /v1/messages request with "thread": {"type": "create"} and the message-threads-2026-08-12 beta header, then continue it on the next turn by passing the response id as previous_message_id. If you use Anthropic’s SDKs, the client.beta.messages.thread(...) helper manages the create-and-continue flow and attaches the beta header automatically.

On the initial create call, you include your full conversation up to that point along with system and tools:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 2048,
  "system": "You are a careful repository refactoring assistant.",
  "tools": [
    {
      "name": "run_tests",
      "description": "Run the project test suite",
      "input_schema": { "type": "object", "properties": {} }
    }
  ],
  "thread": {
    "type": "create"
  },
  "messages": [
    { "role": "user", "content": "Check why the auth test is failing." }
  ]
}

The API returns a standard message response with an id (for example, msg_01XYZ...) that represents the stored conversation including Claude’s reply. On the next turn, you send only the new messages—such as a tool_result or the user’s next prompt—and reference that id:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 2048,
  "thread": {
    "type": "continue",
    "previous_message_id": "msg_01XYZ..."
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01ABC...",
          "content": "FAIL src/auth.test.ts: expected 200, got 401"
        }
      ]
    }
  ]
}

Rules that will trip you up if you skip the docs

Anthropic enforces strict consistency across a thread’s lifetime:

• Create-only fields: You must omit system and tools on every continue request. Sending them again returns a 400 error.
• Fixed fields: Your model, tool_choice, thinking, mcp_servers (except each server’s auth token), context_management, output_config, container skills, top-level cache_control, and the exact set of anthropic-beta header values must match the initial create call. Changing any of them triggers a 400 thread_fingerprint_mismatch error.
• Per-turn fields: You remain free to change max_tokens, stop_sequences, stream, metadata, and service_tier from turn to turn.
• Append-only history: Each response id can only be continued once, and you must always continue from the latest response id. If you need to edit an earlier message or branch the conversation, you have to start a new thread with create.

How long does a message thread last?

A message thread expires 5 minutes after its last request and is permanently deleted from server memory no more than 1 hour after its last use. Every successfully stored response resets the 5-minute timer.

Because threads are held in volatile memory as a best-effort cache, the API response never tells you upfront whether a specific turn was successfully stored. You only find out on the next continue call. If the 5-minute window has elapsed—or if the server evicted the thread early—the API returns a 404 error.

When your client gets a 404, the recovery path is straightforward: resend the full conversation history (along with system and tools) in a fresh "thread": {"type": "create"} request. Your application must remain the source of truth and keep its own complete copy of every message and tool result.

How do message threads work with prompt caching?

Message Threads and prompt caching solve different parts of the long-context problem, and prompt caching is not automatic when you enable threads. Message Threads shrinks the bytes you upload and validate over the network; prompt caching cuts what you pay for repeated input tokens (for example, dropping Sonnet 5.5 input tokens from $2 to $0.10 per million, as broken down in our AI API pricing comparison).

If you want both faster TTFT and lower input token costs, you need to opt in to both. To cache each turn inside a thread, include top-level cache_control on the initial create request and keep sending that same top-level cache_control on every continue request (remembering that top-level cache_control is one of the fixed fields that must match across the thread). Anthropic allows a maximum of 4 cache_control breakpoints when thread is set.

Who should turn Message Threads on?

Teams running long-horizon coding loops, computer-use workflows, or document-heavy multi-turn agents will see the clearest payoff, while teams with strict compliance requirements or batch pipelines may need to pass. If you are new to how tool-using loops differ from ordinary chatbots, our guide on what an AI agent is covers the fundamentals.

Where Message Threads fits best:

• Coding agents: Loops that read files, run compilers, and iterate across dozens of rapid turns within the 5-minute active window. (Anthropic already has it on by default for most Claude Code users.)
• Computer-use agents: Workflows where every turn attaches a fresh desktop or browser screenshot; keeping earlier screenshots on the server avoids re-uploading megabytes of base64 image data on every step.
• Document and image-heavy chats: Interactive sessions where a user uploads large PDFs or image sets and asks rapid follow-up questions. Even if your agent orchestrates external media pipelines—say, drafting scripts and kicking off renders in a tool like AI Studio—keeping the heavy planning context and reference images in a server-side thread keeps the coordinator loop snappy.

Where it is blocked or unsupported as of November 2026:

• Zero Data Retention (ZDR) and HIPAA orgs: Message threads are not ZDR eligible, and organizations with HIPAA readiness enabled cannot use them.
• Unsupported API features: You cannot use thread with Message Batches, token-counting requests that include thread, on-demand compaction, most context-editing strategies (except clear_thinking_20251015 with keep: "all"), or organizations that have Inference hooks turned on.

What I’d actually do

If you maintain an agent harness on the Claude Messages API, I would enable Message Threads anywhere a single task regularly crosses 100k tokens and runs turns less than five minutes apart—provided your compliance posture allows it. Here is the rollout checklist I would follow:

1. Keep your local conversation store untouched. Treat server-held threads strictly as a transport accelerator, never as your database. Append every user turn, assistant reply, and tool result locally just as you do today.
2. Wrap continue in an automatic 404 fallback. When a continue call returns 404 (whether from a 5-minute idle pause or a best-effort eviction), catch it and immediately replay the full local history with "thread": {"type": "create"}, system, and tools.
3. Pair it with top-level cache_control. Never turn on Message Threads expecting your invoice to drop. Put top-level cache_control on both your create and continue calls so you get the 90%+ cached-input discount alongside the TTFT speedup. Check our AI API pricing comparison to model what uncached vs. cached input costs look like at 500k tokens.
4. Lock your thread config at creation time. Audit your agent loop to make sure it does not dynamically mutate tools, system, thinking, or anthropic-beta headers mid-task, or you will hit 400 thread_fingerprint_mismatch errors.
5. Verify ZDR and HIPAA settings first. If your workspace relies on Zero Data Retention or HIPAA readiness, leave Message Threads off—the beta is ineligible for both.

Frequently asked questions

Does Message Threads reduce my Claude API token cost?

No. While each follow-up HTTP request carries only the new messages, Claude still reads the entire conversation history on every turn. You are billed for the full input and output tokens at standard Claude rates, and existing rate limits still apply. To lower your input token bill on repeated context, combine Message Threads with prompt caching.

Do I still need prompt caching if I use message threads?

Yes. Message Threads only keeps the conversation in server memory so you do not have to re-upload and re-validate earlier messages over the network. It does not automatically enable prompt caching. To get cached input pricing on each turn, send top-level cache_control on the initial create request and on every subsequent continue request (up to 4 breakpoints total).

What happens after 5 minutes of idle time?

A message thread expires 5 minutes after its last request (and is deleted from memory no more than 1 hour after its last use). If you send a continue request after the thread has expired, the API returns a 404 status code. Your client should catch that 404 and resend the full conversation with "thread": {"type": "create"} to start a new thread.

Is Message Threads available on AWS, Azure, and Google Cloud?

Yes. According to Anthropic’s November 2, 2026 release notes, the public beta (message-threads-2026-08-12) is available on the direct Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude in Microsoft Foundry.

Does Claude Code already use message threads?

Yes. Anthropic states that message threads are turned on by default for most Claude Code users, where requests between 500k and 1M tokens see a median time-to-first-token reduction of about 35%.

Feature details last checked November 3, 2026. Next review: December 3, 2026.

Sources

• Anthropic, Claude Platform Release Notes (November 2, 2026), checked November 3, 2026
• Anthropic, Make long-running agents faster with message threads, checked November 3, 2026
• Anthropic Documentation, Message threads (message-threads-2026-08-12), checked November 3, 2026
• LoTook, AI API Pricing Comparison, checked November 3, 2026