Claude Message Threads Make Long Agent Loops Faster, Not Cheaper

Anthropic's new API beta stops agents from re-uploading the whole conversation every turn. Here is what it fixes, what it leaves alone, and the one habit it makes non-negotiable.

A long-running agent does something strange on every single turn. It packs up the entire conversation so far, every instruction, every tool result, every file it read an hour ago, and ships the whole thing back to the model. Then it adds one new line at the bottom.

At a few thousand tokens nobody notices. At half a million tokens, that upload is part of why your coding agent sits there thinking before it types the first character of its answer.

Anthropic just changed that for the Claude API. On November 2 it announced message threads in public beta: the client sends the conversation once, and after that sends only what is new. The result is faster first responses on big contexts. The catch is in the fine print, and it shapes how you should build: the API now holds your conversation, but you can only continue it for five idle minutes, and it never tells you whether it kept the latest turn.

So the useful way to think about threads is simple. They are a short-lived cache on Anthropic's side, not memory. Speed goes up. The bill stays put. And your own copy of the transcript becomes the thing everything else depends on.

What a thread actually is

Picture a phone call versus a stack of letters. Without threads, every request to the Messages API (the endpoint you call to get a reply from Claude) is a letter that has to repeat the whole story so far. With threads, it is closer to a phone call. The other side already heard the beginning, so you just say the next thing.

Mechanically, it works like this, per Anthropic's docs:

Your first request sends the full conversation, the system prompt and the tools, plus thread: {"type": "create"}.
Every later request sends only the new messages, plus thread: {"type": "continue", "previous_message_id": "<id>"}, where the ID is the one from the previous response.
Every request in the thread carries the beta header message-threads-2026-08-12.

The docs explain why this helps: "Without a thread, every turn uploads the whole conversation again, and the API validates and tokenizes all of it again. With a thread, most of that work covers only the new turn." Tokenizing, in plain words, is the step where text gets chopped into the units the model reads. Doing it once instead of on every turn is where the time goes.

How much faster, and for whom

Anthropic's own number: for Claude Code users, where threads are now on by default for most people, "requests with 500k to 1M tokens see median TTFT drop by about 35%," according to the announcement. TTFT means time to first token, the pause before the reply starts streaming.

Two things about that figure are worth holding onto.

It is Anthropic's measurement on its own product. Nobody outside has published a comparison yet, and the announcement gives no number for smaller contexts. Expect the win to shrink as conversations get shorter, because there is less to skip re-uploading.

It also tells you who should care. The announcement names long-running coding agents, computer-use agents (agents that drive a desktop by looking at screenshots) and document- or image-heavy workflows. If your chatbot conversations rarely pass a few thousand tokens, threads will barely register. If you run an agent that reads a repository for an hour, they are aimed squarely at you.

Faster is not cheaper

Here is the part that trips people up. Sending less over the wire sounds like it should cost less. It does not.

The announcement says it directly: "Claude still reads the full conversation on every turn, so token usage stays the same." The docs add that "Threads do not change pricing or rate limits."

Think of it as delivery versus reading. Threads make delivery faster. The model still reads the whole file every turn, and you pay for the reading.

If your goal is a smaller bill, the tool for that is still prompt caching, the feature that bills the repeated opening part of a prompt at a reduced rate. And threads do not do it for you. The docs say plainly that "A thread does not cache your prompt for you." To keep caching on, send a top-level cache_control on every request in the thread. One limit to plan around: a threaded request can carry at most four cache breakpoints (the markers that tell the API where a cacheable chunk ends), and the ones on your first request's system prompt and tools count again on every continue request.

The five-minute rule and the silent turn

This is the design detail that should change how you write your agent loop.

The docs describe a thread as "best-effort. It expires 5 minutes after its last request, and the API deletes it no more than 1 hour after its last use. Each response that the API stores restarts the 5 minutes." The API keeps it "in memory, encrypted under a server-managed key," and never writes it to durable storage.

Five idle minutes is shorter than it sounds for an agent. A human reviewer who steps away for coffee, a long test suite, a tool call that waits on a slow deploy: any of those can outlast the window.

The bigger surprise is this line from the docs: "No response, to a create or a continue request, says whether the API stored that turn. You find out on the next continue request." You can get a perfectly good answer back and still discover on the next turn that the API no longer has the thread.

When that happens you get a 404 with the error code thread_not_found, and the response does not say why. The docs list a few other thread errors you should expect to see in logs:

thread_fingerprint_mismatch: you changed a field that must stay fixed for the life of the thread, such as model, tool_choice or thinking.
thread_already_continued: each response ID can be continued only once, so two workers racing on the same thread will collide.
thread_continue_in_flight: another continue from the same ID is still running.
thread_unsupported_request: a feature or org setting the thread cannot handle.

For thread_not_found, the recovery the docs prescribe is to send the full conversation again from your own copy as a new create request, then continue from the new response ID. The 400 errors mostly point at bugs in your own loop.

Which means the API's copy can never be your only copy.

What changes in your agent loop

Threads add a second path to every turn. The fast path continues the thread. The slow path, called replay, rebuilds it from your own transcript. Your code needs both from day one, because the slow path will run in production whether you planned for it or not.

A few rules fall out of the docs:

Pick the fixed settings before the first turn. model, tool_choice, thinking, mcp_servers and the set of beta headers are among the fields locked for the thread (the docs list a few more, such as context_management and output_config). If your agent switches models mid-task (say, a cheaper model for summaries), that switch now means starting a new thread.
System prompt and tools go only on the create request. Sending either on a continue request, even as null, returns a 400.
Some settings stay free. max_tokens, stop_sequences, stream and metadata can change on any turn.
One writer per thread. Because a response ID can only be continued once, parallel workers that share a conversation need a lock, or separate threads.

Put this into practice

The lowest-friction start, if you use the Python SDK, is the thread helper. It wraps create, continue and replay, so you do not track response IDs by hand. The docs list client.beta.messages.thread(...) with thread.send(...), and say the helper replays on its own when the API reports the thread is gone. The catch: it keeps the history in memory, so if your process restarts, that history is gone too.

Here is the shape of the raw call, adapted from the docs example:

import anthropic

client = anthropic.Anthropic()
BETA = ["message-threads-2026-08-12"]

first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},   # keep caching on, every turn
    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=BETA,
)

second = client.beta.messages.create(
    model="claude-opus-5-5",               # must match the create request
    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=BETA,
)

Then, before you ship it, do these four things in order:

Write every message to your own store first. A database row, a JSONL file, whatever your agent already uses for logs. This is the transcript you will replay from. Save each user message before you send it and each reply as soon as it arrives.
Wrap the continue call. On a 404 thread_not_found, resend the full transcript with thread: {"type": "create"} and carry on from the new ID. Log the 400 thread errors loudly; they usually mean your loop changed a fixed field or raced itself. Test it on purpose by waiting six minutes between two turns.
Measure before and after. Log time to first token for a week of real sessions with threads off, then on. If your contexts are small, you may find nothing worth the extra code.
Check your compliance settings. Threads are not eligible for zero data retention (ZDR, the setting where Anthropic keeps no copy of your requests) or HIPAA, and organizations with HIPAA readiness turned on cannot use them, per the docs. If either applies to you, the answer is simply no.

Threads work on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry, according to the same page.

Honest limitations

It is a beta. The header is pinned to a dated version, field rules may change, and nothing here is a stable contract yet.
No storage receipt. You cannot ask the API whether it kept a turn. You only learn on the next request, which makes replay logic mandatory rather than optional.
Five minutes is short for human-in-the-loop work. Any agent that pauses for approvals will replay often, and each replay pays the full upload again.
The speed number is the vendor's. About 35% on 500k to 1M token requests is Anthropic's figure for Claude Code. Your workload is not Claude Code.
It fights with mid-task model switching. Routers that change models per step lose the benefit every time they switch.
Retention rules exclude some teams entirely. ZDR and HIPAA customers are out.
You cannot see or manage a thread. The docs offer no call to list, read or delete one, and threads do not work with Message Batches or token-counting requests.

What to do with this

Threads are a good feature with a narrow job. They make the wait shorter on very long conversations, and they do it by keeping a temporary, in-memory copy of your agent's history on Anthropic's servers: usable for five idle minutes, deleted within the hour.

The work they ask of you is the work a careful agent should already be doing: keep your own transcript, assume any remote state can vanish, and know which settings your loop changes between turns. Build the replay path, turn threads on for your longest-running agent, and compare a week of first-token times. If the numbers move, keep it. If they do not, you have lost nothing but a header.

Sources: Anthropic, "Make long-running agents faster with message threads" (Nov 2, 2026); Claude docs, Message threads (beta header message-threads-2026-08-12, read Nov 3, 2026).