Message Threads: Claude API Documentation
by Anthropic
Cut time to first token on long agent conversations by sending only each turn's new messages to the Claude Messages API.
Overview
Message threads is the Claude Messages API documentation page for a beta feature (header message-threads-2026-08-12) that Anthropic announced on November 2, 2026. Without a thread, every agent turn re-uploads the whole conversation and the API validates and tokenizes all of it again; with one, you send the full conversation, system prompt and tools once with "thread": {"type": "create"}, then continue with only the new messages plus "previous_message_id". The page walks through using the SDK helper (client.beta.messages.thread, then send per turn) and sending the thread field yourself, with two-turn examples in Python, TypeScript, C#, Go, Java, PHP, Ruby, cURL and the ant CLI. It then covers the rules that trip people up: which fields are create-only, which must stay fixed for the life of the thread (model, tool_choice, thinking, mcp_servers, top-level cache_control and others, enforced by a thread_fingerprint_mismatch error), the append-only model where each response id can be continued once, the 5-minute idle expiry with deletion within an hour, and recovery from a 404 thread_not_found by replaying the full conversation. Separate sections explain prompt caching on a thread (a four-breakpoint limit), streaming (continue only after message_stop), refusals, server-side fallbacks and why compaction requires starting a new thread. Anthropic's launch post reports a roughly 35% drop in median time to first token for Claude Code requests of 500k to 1M tokens, and says token usage and rates are unchanged.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~45 min read, plus an hour to wire it into an existing agent loop
- Provider
- Anthropic
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Start a thread with a create request and continue it using previous_message_id on later turns
- ✓Use the SDK thread helper in Python, TypeScript, Go, Java, C#, PHP or Ruby
- ✓Know which request fields are create-only, fixed for the thread, or free to change per turn
- ✓Recover from a 404 thread_not_found by replaying the full conversation in a new create
- ✓Combine top-level cache_control with threads while staying under the four-breakpoint limit
- ✓Handle streaming, pause_turn, refusals and server-side fallbacks without corrupting thread state
- ✓Compact a long conversation by starting a new thread with a summary message
- ✓Judge data-handling fit, since thread contents are held encrypted in memory and the feature is not ZDR-eligible
Highlights
- •Documents every thread error code (thread_fingerprint_mismatch, thread_already_continued, thread_continue_in_flight, thread_unsupported_request) with the fix for each
- •Ships runnable two-turn examples in seven SDK languages plus raw cURL and the ant CLI
- •Lists the concrete causes of a thread_not_found, including tool calls cut off by max_tokens and a first image added to an image-free conversation
- •Honest about the trade-off: latency improves, but Anthropic states token usage, pricing and rate limits stay the same
Who It’s For
Best For
- ✓Engineers running long-lived coding or computer-use agents on the Claude API
- ✓Teams seeing time to first token climb as agent conversations grow into hundreds of thousands of tokens
- ✓Developers building custom agent harnesses who manage conversation state themselves
Prerequisites
- •Working knowledge of the Claude Messages API, including tool use and stop reasons
- •Familiarity with prompt caching and cache_control breakpoints
- •Ability to read one of the supported SDK languages or raw HTTP requests
FAQ
What is Message Threads: Claude API Documentation?
Anthropic's reference documentation for message threads, a public beta feature of the Claude Messages API that keeps a conversation on the server for a few minutes so each request carries only the new messages. It is written for engineers running long coding, computer-use or tool-calling agents who want lower latency without rebuilding their loop.
Is Message Threads: Claude API Documentation free?
Message Threads: Claude API Documentation is free to access.
What level is Message Threads: Claude API Documentation for?
Message Threads: Claude API Documentation is aimed at a intermediate audience. Recommended background: Working knowledge of the Claude Messages API, including tool use and stop reasons, Familiarity with prompt caching and cache_control breakpoints, Ability to read one of the supported SDK languages or raw HTTP requests.
How long does Message Threads: Claude API Documentation take?
Expect roughly ~45 min read, plus an hour to wire it into an existing agent loop. Most learners work through it at their own pace.
What will I learn from Message Threads: Claude API Documentation?
You'll learn: Start a thread with a create request and continue it using previous_message_id on later turns; Use the SDK thread helper in Python, TypeScript, Go, Java, C#, PHP or Ruby; Know which request fields are create-only, fixed for the thread, or free to change per turn; Recover from a 404 thread_not_found by replaying the full conversation in a new create; Combine top-level cache_control with threads while staying under the four-breakpoint limit; Handle streaming, pause_turn, refusals and server-side fallbacks without corrupting thread state; Compact a long conversation by starting a new thread with a summary message; Judge data-handling fit, since thread contents are held encrypted in memory and the feature is not ZDR-eligible.
Topics
Sources
This page was written from 4 sources, 3 on domains other than platform.claude.com.