Claude Message Threads API Guide (2026): Faster Agent Loops Without Resending History

Anthropic added message threads to the Claude Messages API on November 2, 2026. The release note is short, and it is easy to skim past. If you run long agent loops, though, it touches a problem you already pay for: every turn re-uploads the entire conversation, and the API validates and tokenizes all of it again. On a 60-turn coding agent, most of each request is history the model has already seen.

This guide covers what threads do, how to call them with curl and Python, what they cost, and where they don't help. I'd treat this as a beta feature for now. The rough edges are documented, and they matter.

What changed on November 2

Before threads, every request to the Messages API carried the full conversation, the system prompt, and the tool definitions. With a thread, you send all of that once. On each later turn you send only the new messages and point at the previous response. The API rebuilds the conversation on its side before it calls the model.

Anthropic's stated goal is lower time to first token and smaller requests, especially as conversations grow. The response itself is the usual message object, so your parsing code stays the same.

How a thread works

There are two request types, and the difference is small enough to get wrong:

• Create. Send the full conversation, system, and tools, and add "thread": {"type": "create"}. The API stores the conversation, including Claude's reply, under the response id.
• Continue. Send only the new messages, add "thread": {"type": "continue", "previous_message_id": "..."}, and leave out system and tools. The thread keeps the values from the create request.

Threads are best-effort. Each stored response restarts a 5-minute window. If the window lapses, a continue request returns a 404. Your fix is to send the full conversation in a new create request and continue from that response's id. Keep your own copy of every message so you can do this. The API doesn't tell you on the current turn whether it stored the last one. You find out on the next continue request.

Two-turn example with curl

This follows the pattern in Anthropic's docs. You need jq installed to pull the response id.

export ANTHROPIC_API_KEY="your-key"

# Turn 1: create the thread with the full conversation
RESP=$(curl -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "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"}
  }')

MSG_ID=$(echo "$RESP" | jq -r '.id')
echo "$RESP" | jq -r '.content[0].text'

# Turn 2: send only the new message, and leave out system and tools
curl -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "messages": [{"role": "user", "content": "How long does standard shipping usually take?"}],
    "thread": {"type": "continue", "previous_message_id": "'"$MSG_ID"'"}
  }' | jq -r '.content[0].text'

Note that cache_control still matters here. Threads change how much you send per turn. Caching decides how much of that prefix you pay full price for.

Python with the SDK thread helper

If you use the Python SDK, the thread helper builds the create and continue requests for you and adds the beta header. It keeps the conversation in memory for the life of the helper object, so a restarted worker starts over.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

# Creating the helper sends no request
thread = client.beta.messages.thread(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
)

# First send creates the thread
first = thread.send({"role": "user", "content": "Hi! I have a question about an order."})
for block in first.content:
    if block.type == "text":
        print(block.text)

# Second send continues it with only the new message
second = thread.send({"role": "user", "content": "How long does standard shipping usually take?"})
for block in second.content:
    if block.type == "text":
        print(block.text)

The helper also handles the replay path after a 404, which is the part people tend to forget when they roll their own client.

Where threads help, and where they don't

Threads pay off in agent loops. A tool-using agent might make 20 to 80 calls while it works through one task, and each call adds a tool result. Without a thread, the request grows every turn. With a thread, each request carries only the new tool output.

They don't help much for one-shot calls. If each request is a fresh prompt with no history, you have nothing to gain. A classifier, a batch summarizer, or a single extraction call should stay on the plain Messages API.

There's one more thing to be clear about. Anthropic's docs describe threads in terms of request size and time to first token. The cost math in this article uses prompt caching rates, which are the numbers the pricing page lists. Check your usage analytics to see what threads do to your own bill.

Pricing you can plan around

These are the Claude 5.5 rates from Anthropic's pricing page, in USD per million tokens. Threads are supported on all three models below.

A worked example makes the caching effect concrete. Say your agent carries a 40,000-token prefix through 20 turns on Sonnet 5.5, and every turn lands inside the 5-minute cache window. Without caching, the prefix costs $2 per million tokens each turn, or $0.08 per turn and $1.60 total. With caching, the first turn writes the prefix at $2.50 per million, or $0.10. The next 19 turns read it at $0.10 per million, about $0.004 each, or $0.076 total. The cached run comes to about $0.18 for the prefix, before output tokens. Your numbers will differ, but the ratio is the point. You can estimate your own prompt sizes with the token counter, then run the totals through the API cost calculator.

Model comparison for thread workloads

My default for a thread-based agent is Sonnet 5.5, with Opus reserved for the steps where the extra capability changes the result. Mixing models across turns works only if your replay code can rebuild the thread on a different model, so test that before you depend on it.

Caveats before you ship it

• Beta. Every request needs the message-threads-2026-08-12 header. Pin it, and watch the release notes for changes.
• Short memory. A thread expires 5 minutes after its last request. Long pauses between turns mean a replay.
• Data retention. Threads are not ZDR eligible. Thread contents stay in memory, encrypted under a server-managed key, and are deleted within an hour of last use. If your compliance terms require ZDR, keep threads out of that path.
• Your copy is the source of truth. Store every message on your side. A 404 is a normal event, not a crash.

If you're building agents that need a second route for bursts or regional issues, KissAPI exposes an OpenAI-compatible endpoint that can sit beside your Claude flow. Threads are only one piece of keeping a long-running agent cheap and reliable, so it's worth wiring the fallback before the traffic spike, not during it.

Frequently asked questions

Are Claude message threads generally available?

No. As of Anthropic's November 2, 2026 release notes, message threads are in beta. Requests need the header message-threads-2026-08-12.

How long does a thread last?

It expires 5 minutes after its last request, and each stored response restarts that window. The API deletes thread contents no more than 1 hour after the last use.

Can I use message threads with Zero Data Retention?

No. Anthropic's docs list message threads as not ZDR eligible. Using threads doesn't affect your use of other ZDR eligible features, but thread data follows the retention rules above.