ClaudeMessages APIConversation StateAgent

Claude message threads expire quickly. Keep your own conversation history.

The Messages API beta can send only new turns, but threads expire and constrain request fields. Learn the create/continue flow, precise 404 recovery, and streaming boundaries.

Claude message threads expire quickly. Keep your own conversation history.

An agent running dozens of tool calls repeatedly uploads much of the same conversation. The message threads beta, announced on November 2, lets later requests send new messages with the previous response ID instead.

Treat the server copy as temporary. A thread expires after 5 minutes without a request and is deleted no more than 1 hour after its last use. Your application still needs the complete conversation to recover after expiry, a process restart, or a configuration change.

This article checks the official documentation on November 16, 2026. It covers the Claude API beta header message-threads-2026-08-12, not Managed Agents session threads. The sample bodies received offline syntax checks; we have not run authenticated requests or validated a third-party channel.

Send everything once, then append new messages

Create a thread with the full conversation and any system and tools fields:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": "Use only the public demo policy supplied by the user.",
  "messages": [
    {"role": "user", "content": "Demo policy: unopened items can be returned within 7 days. Summarize it."}
  ],
  "thread": {"type": "create"}
}

Send this body to the official POST https://api.anthropic.com/v1/messages, using your official credentials, required version header, and the beta header above. Save the request and the response's complete assistant content. The next body sends only the new turn:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Does that demo policy mention customized items?"}
  ],
  "thread": {
    "type": "continue",
    "previous_message_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"
  }
}

The sample policy says nothing about customized items, so the desired answer acknowledges missing information. We did not obtain a live answer. Use the newest response ID on every turn. Do not resend the previous assistant response in a continue request: the server already has it.

A full create request is followed by new messages and the latest response ID

Smaller uploads do not mean the model sees only the new turn. The API reconstructs the conversation before inference. Threads also do not enable prompt caching automatically. The prompt-caching overview explains the separate concept; use the linked Claude documentation for current thread-specific settings.

Field changes have different rules

Omit system and tools on continue requests; even sending them as null is an error. Fields such as model, thinking, tool_choice, and output_config stay fixed, as does the set of beta headers. Other fields, including max_tokens and stream, can change.

ChangeCurrent behavior
New user turn or tool resultsAppend new messages with the latest ID
Output cap or streamingMay change between turns
Model, initial instructions, or tool definitionsCreate a new thread using your full history
Branch from an earlier turnCreate a new thread; do not continue one response ID twice

A fixed-field mismatch returns thread_fingerprint_mismatch. Each response ID can be continued once, so serialize calls to a thread. Branches need independent histories and new threads.

When rebuilding with changed system or tools, account for thinking-block prefix rules too. A new thread ID does not repair edited history. The Fable thinking-prefix article explains that separate constraint.

Recover specifically from a missing thread

A nonexistent model can also produce 404. Check that error.details.error_code is thread_not_found before attempting a full-history replay.

Then send your complete local conversation in a new create request, with the original system and tools. Include assistant content and tool results you already received. Rebuilding model context does not require executing completed tools again. Continue from the new response ID after recovery.

A verified thread_not_found error triggers replay from application history

Expiry is only one possible cause. A turn might not have been stored, might still be generating, or might belong to a different identity or workspace. The error does not identify the cause. The SDK helper attempts one full replay after this 404, but keeps its conversation only in the helper object's memory. It is not persistent application storage.

Keep business-action records separately. Restoring a conversation does not authorize another order, notification, or file write. The workflow recovery guide covers that distinction.

A response ID arrives before a stream is complete

Streaming supplies the ID in message_start. Wait for message_stop before continuing from it; an earlier request can receive 404. Even a successful response does not confirm that the API stored the turn. The next continue request reveals whether it can be reused.

Test normal turns, expiry, process restart, fixed-field changes, stream interruption, and completed-tool preservation separately. Use public fixtures and keep credentials and private content out of diagnostic logs.

Normal turns, expiry, restart and stream completion require separate checks

Thread contents remain in encrypted memory rather than durable storage, but the feature is still not ZDR eligible. Short-lived memory is not a zero-retention promise. For Nbility, first check the Claude compatibility scope for the channel's handling of thread, beta headers, and continuation. This article has not established that support; ordinary Messages requests are insufficient evidence. A related change from the same period: supported models now add a text watermark to their output, including text produced inside a thread.

Related posts

Returning files in Gemini tool results
GeminiFunction CallingFiles

Returning files in Gemini tool results

Gemini multimodal tool results need a valid call ID, typed content, and accessible bytes or a file URI. A filename alone does not deliver the artifact.

Claude's text watermark is live: which models carry it, and who can check
ClaudeText WatermarkContent Provenance

Claude's text watermark is live: which models carry it, and who can check

Since November 16, 2026, supported Claude models watermark their text output. Here is what the watermark actually encodes, which models and platforms carry it, when sampling parameters weaken it, and why only a few organizations can detect it today.

Run your Agent workflow through Nbility

Get an API key and connect OpenAI-compatible models and developer tools from one place.

Get an API key