Claude message threads: what they are and how to use them

What message threads are

Without a thread, every turn of an agent loop uploads the full conversation again, and the API validates and tokenizes all of it again. A coding agent makes hundreds of requests in a session, so once the conversation reaches hundreds of thousands of tokens, that resending delays the start of Claude's answer. With a thread, the API keeps the conversation between turns and most of that work covers only the new turn.

• Faster first token: Anthropic measured a median drop of about 35% on Claude Code requests of 500k to 1M tokens. The longer the conversation, the more it helps.
• Smaller requests: each turn carries only new messages, tool results or screenshots.
• Same tokens and price: Claude still reads the full conversation every turn, and pricing and rate limits don't change.
• Short-lived: a thread expires 5 minutes after its last request and is held in memory, encrypted, never written to disk.
• Where: the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry, on every model.

With and without a thread

How to use message threads in your own agent

Claude Code already does this for you. To use threads in an agent you build on the Messages API, the SDK's thread helper is the shortest path.

1. Create a thread helper

   Pass the same fields as a Messages request. The helper adds the message-threads-2026-08-12 beta header, creates the thread on the first turn, sends only new messages after that, and keeps the full conversation in memory.

   import anthropic
   
   client = anthropic.Anthropic()
   
   # Create the helper. This call sends no request.
   thread = client.beta.messages.thread(
       model="claude-opus-5-5",
       max_tokens=1024,
       cache_control={"type": "ephemeral"},
       system="You are a coding agent. Keep replies short.",
   )
   
   # Turn 1 creates the thread and sends the full conversation
   thread.send({"role": "user", "content": "Read the failing test and explain it."})
   
   # Turn 2 sends only the new message
   reply = thread.send({"role": "user", "content": "Now fix it."})

2. Or send the thread field yourself

   With cURL or a plain create call, add thread to every request and send the beta header on each one. Always continue from the latest response id; each id can be continued once.

   # Turn 1: the full conversation, plus
   "thread": {"type": "create"}
   
   # Every later turn: only the new messages, no system or tools, plus
   "thread": {"type": "continue", "previous_message_id": "<id of the last response>"}
   
   # On every request of the thread
   anthropic-beta: message-threads-2026-08-12

3. Keep model and settings fixed

   system and tools go on the first request only. model, thinking, tool_choice, the top-level cache_control and the beta headers must stay the same on every turn; a change returns a 400 error with thread_fingerprint_mismatch. To change them, start a new thread.

4. Keep your own copy and replay on 404

   Threads are best-effort. When a continue request returns 404 with thread_not_found (the thread expired, the last turn wasn't stored, or a fallback model wrote it), send the full conversation again in a new create request. The SDK helper does this once by itself.

5. Turn on prompt caching

   A thread doesn't cache your prompt for you. Send a top-level cache_control on every request so each turn reads the earlier conversation from the cache; a request with thread can carry at most 4 breakpoints.

Source: Anthropic's message threads docs

Limits and what threads don't support

• Not with Message Batches, token counting, compaction on demand, or context editing (apart from clear_thinking_20251015 with keep: "all").
• Not for organizations with HIPAA readiness or Inference hooks; those requests return a 400 error with thread_unsupported_request.
• Not eligible for zero data retention: the API holds a thread in memory and deletes it no more than 1 hour after its last use.
• There's no API to list, read or delete a thread, and a thread is append-only. To compact, start a new thread from your own summary.
• After a refusal, don't continue the thread: start a new one without the turn that led to it.
• Use the same API key and workspace for every request of a thread, or it can't be continued.

What it means for Claude Code users

You don't need to change anything: Anthropic says threads are on by default for most Claude Code users. The gain shows in long sessions, where a turn deep into a big conversation starts answering sooner. Your usage doesn't drop, since Claude still reads the whole conversation each turn.

Per the API docs, a thread expires 5 minutes after its last request. When you come back to a session after a longer pause, the first request sends the full conversation again, and the turns after it are fast. That's also what happens to a proactive Claude Code session that wakes on a schedule.

Keep long Claude Code sessions working on their own

Message threads make long sessions faster; Crewmark makes them proactive. It gives a Claude Code, Codex, DeepSeek Harness or OpenCode session a role, a goal and working hours, and wakes it on a heartbeat in the same conversation, so it keeps its context and takes the next issue from a board.

1. Turn a session into an employee

   Pick a role such as software engineer or SEO specialist, write its goal as a number, and run the setup command in Claude Code.

2. Let the heartbeat start the work

   During its working hours the employee wakes every 15, 30 or 60 minutes in the same conversation; see how to make Claude Code proactive. Several can run side by side, as in multiple Claude Code agents.

3. Assign issues and answer its messages

   Put work on the board; the employee takes it, comments as it goes and messages you when it needs a decision. Read what an AI employee is.

Claude message threads FAQ