Skip to main content
Overhead flat lay on slate-blue linen: a wooden spool of red thread unwinding across the frame into a steel needle beside a brass sand timer, a metaphor for Claude message threads that expire five minutes after the last request
9 min readBy Carlos Aragon

Claude Message Threads: Tested TTFT, 404s and Cost

Claude message threads make long agent loops faster, not cheaper. With prompt caching on both sides, they cut median time to first token by about 17% once a conversation passed 100K tokens, shrank each request from 376 kB to 21 kB, and left the token bill exactly where it was. Below 60K tokens I couldn't measure a difference. I sent 180 benchmark requests to Claude Haiku 5.5 and Sonnet 5.5 this morning, timed the 5-minute expiry, and triggered every thread error I could. One of them isn't an error at all, and it's the one that will cost you money.

What Are Claude Message Threads?

A message thread keeps your conversation on Anthropic's side for a few minutes. It shipped in beta on November 2, 2026 behind the message-threads-2026-08-12 header. The first request carries everything and says create. Every later request carries only the new messages plus the id of the last response:

# turn 1: full conversation + system + tools, and create the thread
{"model": "claude-haiku-5-5", "max_tokens": 1024,
 "cache_control": {"type": "ephemeral"},
 "system": "...", "tools": [...],
 "messages": [{"role": "user", "content": "Log batch 1: ..."}],
 "thread": {"type": "create"}}

# turn 2+: only the new messages, no system, no tools
{"model": "claude-haiku-5-5", "max_tokens": 1024,
 "cache_control": {"type": "ephemeral"},
 "messages": [{"role": "user", "content": "Log batch 2: ..."}],
 "thread": {"type": "continue", "previous_message_id": "msg_011C..."}}

# header on every request
anthropic-beta: message-threads-2026-08-12

Without a thread, an agent loop re-uploads the whole conversation on every turn, and the API has to validate and tokenize all of it again. That's the work threads remove. They don't remove the model reading the conversation. The official message threads docs say pricing and rate limits don't change, and my numbers agree.

Do Message Threads Actually Make Claude Faster?

I simulated an ops agent reading order logs: each turn appended about 10.7K tokens of log lines and asked for a one-word reply. Two copies of the loop ran in lockstep, one sending the full conversation every turn and one using a thread. Both had the top-level cache_control on, because comparing a thread against an uncached loop would be rigging the test. Haiku ran 3 loops of 18 turns, Sonnet ran 2 loops of 14. Median time to first token:

Conversation sizeModelFull resendThreadChange
11K-33K tokens (turns 1-3)Haiku 5.50.753 s0.741 snoise
44K-98K tokens (turns 4-9)Haiku 5.50.781 s0.745 s-5%
108K-194K tokens (turns 10-18)Haiku 5.51.091 s0.909 s-17%
11K-33K tokens (turns 1-3)Sonnet 5.51.087 s1.089 snoise
44K-98K tokens (turns 4-9)Sonnet 5.51.098 s1.185 snoise
108K-151K tokens (turns 10-14)Sonnet 5.51.304 s1.077 s-17%

The win shows up late and it shows up in the tail. On Haiku past 100K tokens, the p90 went from 1.74 s to 1.20 s, a 31% drop, which matters more to a user waiting on a voice agent or a chat UI than the median does. The full-resend loop had more slow outliers as the payload grew; the thread loop stayed flat.

The request size is the dramatic number. At turn 18 the full-resend body was 376 kB and the thread body was 21 kB, every single turn. Across one 18-turn Haiku loop that's 3.6 MB of upload versus 0.38 MB. On my test machine upload time wasn't the bottleneck: 376 kB is roughly 20 ms at the ~18 MB/s it pushes. On a serverless function with a slow egress path, or with screenshots and PDFs in the history, the gap will be bigger than mine. If you've ever hit the request ceiling, this is also the cleanest fix for a 413 request too large in a long loop.

One honest caveat: that's 54 turns per mode on Haiku and 28 on Sonnet, on one connection, on one Sunday morning. Treat 17% as "real and modest", not as a constant.

Do Message Threads Save Money?

No. Same loop, 8 turns, caching off on both sides: the full-resend version billed 392,706 input tokens and the thread billed 392,690. With caching on, the 18-turn Haiku loops wrote 583,230 vs 583,228 cache tokens and read 4,973,642 vs 4,973,608. That's the same bill with a rounding error.

A thread is not a cache. Without cache_control, a thread re-bills the entire conversation at full input price on every turn, exactly like the old way. If you want the cost drop, that's still prompt caching.

The cache_control Trap the Docs Don't Catch

The docs list the top-level cache_controlas a "fixed" field: send the same value on every request, or get thread_fingerprint_mismatch. That's what happens when you change thinking or output_config. It's not what happens with cache_control. I created a 33K-token thread with it and continued without it:

create WITH cache_control, continue WITHOUT it
  continue -> 200   input_tokens: 33,538   cache_read: 0      <- full price

create WITHOUT cache_control, continue WITH it
  continue -> 200   input_tokens: 4        cache_write: 33,534

create WITH, continue WITH (what you want)
  continue -> 200   input_tokens: 4        cache_read: 33,514

No error. The continue request just stopped caching and billed all 33,538 tokens at full price. On a 150K-token agent loop that's the difference between paying for cache reads and paying full input on every turn, with nothing in your error logs. The easy way to get here is a refactor where the create path and the continue path build their request bodies separately. Put the fixed fields in one dict that both paths use, and alert when cache_read_input_tokens drops to zero on a continue. My cache miss diagnostics post has the rest of that checklist.

When Does a Claude Message Thread Expire?

The docs say 5 minutes after the last request. I opened six threads at the same moment and continued each one on a different schedule:

Continue timingResult
4:00 after create200, continued
4:50 after create200, continued
5:20 after create404 thread_not_found
6:30 after create404 thread_not_found
400 error at 3:00, then continue at 5:20404 (the failed request didn't extend it)
Continue at 3:00, then 4:30 after that (7:31 total)200 (a stored turn restarts the clock)

The 5 minutes is real, and only a stored response resets it. That matters for human-in-the-loop agents. If your agent waits for someone to approve a refund, the thread is gone by the time they click. Same for any tool call that takes longer than a few minutes. Plan for the replay path being the normal path in those flows, not an edge case.

Which Thread Errors Will You Actually Hit?

Every row below is a real response from today's runs:

What I sentWhat came back
Sent system or tools on a continue400, no error_code. The message tells you exactly what's wrong
Sent system: null on a continue400 "system: Input should be a valid array" (misleading)
Changed thinking or output_config400 thread_fingerprint_mismatch, names the field
Changed max_tokens, stop_sequences, metadata200, these are free to change
Continued the same id twice400 thread_already_continued
Continued while the previous continue was still streaming400 thread_continue_in_flight
Continued from an id taken from message_start, before message_stop404 thread_not_found, but the same id worked once the stream finished
Re-sent the previous assistant turn in messages404 thread_not_found (not a 400)
Continued after a tool call cut off by max_tokens404 thread_not_found
Five cache_control breakpoints400 thread_unsupported_request, unsupported: [cache_control]
thread field without the beta header400 "thread: Extra inputs are not permitted"
thread field on /v1/messages/count_tokens400 "thread: Extra inputs are not permitted"
Made-up message id404 thread_not_found

Two rows are worth a second look. Re-sending the previous assistant message is a bug in your code, but the API answers 404 thread_not_found, so a naive client replays and carries on without ever finding the bug. And the streaming case: the response id arrives in message_start, but continuing from it before message_stopgets a 404. The good news is that 404 doesn't burn the id. Wait for the stream to end and the same id works.

Always check error.details.error_code, not just the status. A typo in the model name is also a 404, with no error code. Replaying on that just fails twice.

A Replay-Safe Thread Client in Python

The SDKs ship a thread helper (client.beta.messages.thread(...)in Python SDK 2.6.0) that does most of this for you, and you should probably use it. But the helper keeps history in memory only. If your agent runs across workers or survives restarts, you're writing this yourself. I ran this version against the live API, including a forced thread_not_found that replayed and then continued normally:

import anthropic

client = anthropic.Anthropic()
BETA = ["message-threads-2026-08-12"]
FIXED = dict(model="claude-haiku-5-5", max_tokens=1024,
             cache_control={"type": "ephemeral"})  # send on EVERY turn, or caching silently stops
SYSTEM = "You are an ops agent. Keep replies short."
TOOLS = []  # your tool definitions

history = []  # your copy of the conversation is the source of truth
prev_id = None


def turn(new_messages):
    global prev_id
    history.extend(new_messages)
    if prev_id:
        try:
            r = client.beta.messages.create(**FIXED, betas=BETA, messages=new_messages,
                                            thread={"type": "continue", "previous_message_id": prev_id})
            return _keep(r, new_messages)
        except anthropic.NotFoundError as e:
            if _code(e) != "thread_not_found":
                raise  # a 404 for a bad model name looks the same without this check
        except anthropic.BadRequestError as e:
            if _code(e) not in ("thread_already_continued", "thread_continue_in_flight"):
                raise  # fingerprint mismatch / unsupported request = a bug in your code
    # first turn, or replay after the thread is gone
    r = client.beta.messages.create(**FIXED, betas=BETA, system=SYSTEM, tools=TOOLS,
                                    messages=history, thread={"type": "create"})
    return _keep(r, new_messages)


def _code(e):
    return ((e.body or {}).get("error", {}).get("details") or {}).get("error_code")


def _keep(r, new_messages):
    global prev_id
    if r.stop_reason == "refusal":  # never continue a refused turn: drop it, start over
        del history[-len(new_messages):]
        prev_id = None
        return r
    history.append({"role": "assistant", "content": r.content})
    cut_tool_call = r.stop_reason == "max_tokens" and r.content and r.content[-1].type == "tool_use"
    prev_id = None if cut_tool_call else r.id  # a cut-off tool call is never stored
    return r

FIXED is the important part. Create and continue share one source for model, cache_controland everything else that has to match, so the silent caching trap above can't happen. If you're still on an older SDK, the 2026-10-21 API version migration comes first.

Should You Turn Message Threads On?

For agent loops that routinely pass 100K tokens and run turns back to back: yes. That's coding agents, research agents, anything that piles tool output into the context. The latency gain is modest but free, and the smaller requests make everything around the call cheaper.

For short chats, batch jobs and approval flows with long pauses: skip it. You add a replay path for no measurable gain. Threads also don't work with Message Batches, token counting, or compaction, and they aren't ZDR-eligible. If you need compaction, you compact in your own code and start a new thread from the summary.

How I Tested This

November 8, 2026, from a Mac mini in Allen, TX. Raw http.client with streaming and per-event timestamps, API version 2026-10-21, connection opened before the clock started. Time to first token is the first content_block_delta. Haiku 5.5 had thinking disabled; Sonnet 5.5 used between_tools. Each loop had its own random nonce in the system prompt so loops couldn't share a cache. The expiry and error tests used separate fresh threads, and the snippet ran on anthropic 2.6.0. Total API spend for everything: about $2.83.

Is Your Claude Agent Slow or Expensive?

I build and tune Claude agents in production: caching, threads, tool loops and the bills that come with them. Send me your request logs and I'll tell you where the time and money go.

Related Posts