Claude APIのメッセージスレッド(message threads)とは|使い方・コード例・キャッシュ・エラー一覧
Claude APIのメッセージスレッド(ベータ)の使い方を整理。create/continue/replayのコード例、プロンプトキャッシュとの組み合わせ、thread_not_foundなどのエラー一覧、料金が変わらない理由と5分の期限を公式ドキュメントからまとめます。

Anthropicは2026年11月2日(米国)、Claude APIのMessages APIに**メッセージスレッド(message threads)**をパブリックベータで追加しました。最初の1回だけ会話全体を送れば、2回目からは新しいメッセージと直前の返答のIDだけを送れば済みます。返答が始まるまでの時間(TTFT)は短くなりやすい一方、料金とトークンの量は変わりません。
この記事は2026年11月3日に公開し、11月7日に公式ドキュメント・お知らせ・リリースノートを取り直して、コード例、プロンプトキャッシュとの組み合わせ、エラー一覧を加えました。編集部にClaude APIキーがないため、速度の実測はしていません(理由は後述)。
何が変わるのか
これまでのMessages APIは、毎回それまでの会話をすべて送り直す必要がありました。長く動くエージェントでは、ツールの結果やファイルの変更が積み重なり、1回のリクエストが大きくなります。スレッドを使うと、APIが会話をサーバー側に一時的に持ち、送られた差分と合わせて元の会話を組み立て直してからモデルに渡します。
Anthropicによると、Claude Codeの多くの利用者ではすでに既定で有効で、50万〜100万トークンのリクエストでは返答が始まるまでの時間(中央値)が約35%短くなりました。向いているのは、長いコーディングエージェント、スクリーンショットを抱えるコンピュータ利用、文書・画像が多い流れなど、文脈が太くなるほど効きやすい、とお知らせに書かれています。
Managed Agentsのセッション・スレッドとは別物です。メッセージスレッドはMessages APIのリクエストを小さくする仕組みです。
使い方(create → continue → replay)
- 作成(create):いつもどおり会話全体・system・toolsを送り、
thread: { type: "create" }を足します - 続ける(continue):前の返答より後のメッセージだけを送り、
thread: { type: "continue", previous_message_id: "前の返答のid" }を足します。systemとtoolsは送りません(送ると400) - やり直す(replay):続けられないときは404(
thread_not_found)が返るので、会話全体を送って作り直します
毎回、ベータのヘッダー message-threads-2026-08-12 が必要です。SDKのスレッド補助(thread helper)は、ヘッダー付与・continue・404時の作り直しまで自動で行います。
送るフィールドの分け方
公式ドキュメントの表を要約すると、次のとおりです。
| 区分 | 主なフィールド | ルール |
|---|---|---|
| 作成時だけ | system、tools | continueでは送らない(nullでも400) |
| 固定 | model、tool_choice、thinking、mcp_servers(認証トークン以外)、context_management、output_config、containerのskills、トップレベルのcache_control、anthropic-betaの集合 | 毎回同じ値。違うと400(thread_fingerprint_mismatch) |
| 自由 | max_tokens、stop_sequences、stream、metadata、service_tierなど | ターンごとに変えてよい |
スレッドは追記のみで、各返答IDは1回だけcontinueできます。途中のメッセージを直したり分岐したりするときは、新しいcreateで始めます。stop_reason が pause_turn のときは、空のmessagesでcontinueして再開します。
Python(SDK helper)
公式の例に沿った最小形です(モデル名はドキュメントの例どおり)。helperを作った時点ではリクエストは飛びません。
import anthropic
client = anthropic.Anthropic()
# ヘルパー作成(この時点ではリクエストなし)
thread = client.beta.messages.thread(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"}, # 任意。毎回キャッシュしたいとき
system="あなたは短い返答をするサポート担当です。",
)
# 1通目: 会話全体を送ってスレッド作成
thread.send({"role": "user", "content": "注文について質問があります。"})
# 2通目: 新しいメッセージだけ送る
second = thread.send(
{"role": "user", "content": "通常配送は何日くらいかかりますか?"}
)
for block in second.content:
if block.type == "text":
print(block.text)
TypeScript(SDK helper)
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const thread = client.beta.messages.thread({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system: "あなたは短い返答をするサポート担当です。"
});
await thread.send({ role: "user", content: "注文について質問があります。" });
const second = await thread.send({
role: "user",
content: "通常配送は何日くらいかかりますか?"
});
for (const block of second.content) {
if (block.type === "text") {
console.log(block.text);
}
}
cURL(自分で thread を付ける)
# 1通目: 会話全体を送って作成
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: message-threads-2026-08-12" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "あなたは短い返答をするサポート担当です。",
"messages": [{"role": "user", "content": "注文について質問があります。"}],
"thread": {"type": "create"}
}'
# 2通目: 新しいメッセージと previous_message_id だけ
# (message_id は1通目の応答の id。system / tools は送らない)
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: message-threads-2026-08-12" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"messages": [{"role": "user", "content": "通常配送は何日くらいかかりますか?"}],
"thread": {"type": "continue", "previous_message_id": "'"$message_id"'"}
}'
会話の正本はアプリ側に残します。create/continueの応答には「保存できたか」は書かれず、次のcontinueで初めて分かります。SDK helperはプロセス内のメモリにだけ会話を持ち、ディスクには書きません。
プロンプトキャッシュとの組み合わせ
スレッドは「送る量」を減らしますが、プロンプトキャッシュを自動では付けません。キャッシュしたいときは、これまでどおり cache_control を自分で置きます。
ブレークポイントの置き方(上限4)
- 毎回のターンをキャッシュしたいなら、トップレベルの cache_control(例: type ephemeral)をスレッドの全リクエストに同じ値で付けます。固定フィールド扱いです
- create時に tools/system/メッセージ途中へ付けたブレークポイントは、後続ターンでも効き続けます(最後のメッセージブロック上のものは、そのリクエストで書き込む用)
- ブレークポイントは後から動かしたり消したりできません(continueでは過去メッセージを送り直せないため)
- thread付きのリクエストは、cache_control ブレークポイントを最大4つまで。トップレベルも1つに数えます。system/tools上のものはcontinueでも再カウントされます。5つ目は400(thread_unsupported_request、unsupported に cache_control)
- replay(新しいcreate)では、古いメッセージ上のブレークポイントを外し、最後のブロックに1つ残すなどして4以内に収めます。SDK helperはreplay時に過去ターンのブレークポイントを外します
OpenAIの12時間キャッシュとの違い
関連記事のOpenAIのプロンプトキャッシュ12時間との対比です(公式で確認できた範囲)。
| 項目 | Claude メッセージスレッド | Claude プロンプトキャッシュ | OpenAI プロンプトキャッシュ(12h) |
|---|---|---|---|
| 主な効果 | リクエストサイズ縮小・TTFT短縮 | 読む部分の単価低下・再計算の節約 | 同上(保持の下限を12時間に延ばせる) |
| 料金 | 変わらない(毎回全文を読む) | キャッシュ読みは安い単価 | 書き込みは30分1.25倍/12時間2.5倍、読み0.1倍など |
| 保持 | 最後のリクエストから5分(最長1時間で削除) | モデル・指定による(スレッドとは別) | 最低12時間(それ以上残ることも。ガイド上の上限の説明あり) |
| 指定 | thread create/continue | cache_control(トップレベルまたはブロック) | prompt_cache_options.ttl など |
| 併用 | ― | スレッドと併用可(毎回自分で指定) | Claudeのスレッドとは別製品 |
スレッドだけ使うと送るデータは小さくなりますが、トークン代は下がりません。長く続くエージェントでは、スレッドでTTFTを抑えつつ、cache_controlで単価を下げる組み合わせが公式の想定に近いです。
エラー一覧
モデルが動く前に返るエラーです。トークンは使わず、スレッドの期限も進みません。
thread_not_found(404)
continueできないときです。応答は原因を言いません。公式が挙げる例は次のとおりです。
| 原因の例 | 対処の要点 |
|---|---|
| スレッドの期限切れ(最後のリクエストから5分) | 手元の会話全体で新しいcreate |
| 直前のターンをAPIが保存しなかった(例: max_tokensで切れたツール呼び出し) | 同上。SDK helperは自動でreplay |
| フォールバックモデルが直前の返答を書いた | フォールバック用の手順で新しいcreate(後述) |
| 直前の返答がまだ生成中 | 終わるのを待つか、replay |
| 別の組織/ワークスペースからのリクエスト | 同じキー・ワークスペースで通す |
| 作成時と違うユーザー/サービスアカウント | 同じ主体で通す(レガシーのワークスペースキーもスレッド全体で同じキー) |
| 保存済み会話が受け取れない差分(例: 画像が初めて登場) | 全文を載せた新しいcreate |
モデル名が存在しない場合も404になるため、replayする前に error.details.error_code が thread_not_found かを見ます。
その他のスレッドエラー
| ステータス | error_code | 意味 | すること |
|---|---|---|---|
| 400 | thread_fingerprint_mismatch | 固定フィールドが作成時と違う | 同じ値に戻すか、新しいスレッドで作り直す |
| 400 | thread_already_continued | その返答IDはすでにcontinue済み | 最新の返答IDへ。受け取れていなければreplay |
| 400 | thread_continue_in_flight | 同じIDへのcontinueが進行中 | 終わるのを待つかreplay |
| 400 | thread_unsupported_request | 非対応機能や組織設定 | その機能を外すか、threadなしで全文送信 |
thread_unsupported_request の unsupported 値
error.details.unsupported があるとき、公式が示す値は次です(今後増える可能性あり。知らない値なら thread なしで送る)。
| 値 | 意味 |
|---|---|
| context_management | スレッド非対応のコンテキスト管理やコンパクション |
| cache_control | cache_control ブレークポイントが4を超えた |
| fallbacks | 組織がスレッドとfallbacksの併用を使えない |
| hipaa | HIPAA readiness が有効な組織 |
| inference_hooks | Inference hooks が有効な組織 |
フォールバックと拒否
サーバー側フォールバックを使うなら、fallbacks はスレッドの全リクエストに付けるか、どれにも付けないかに揃えます。フォールバックモデルが書いたターンは保存されないため、その id からはcontinueできません。usage.iterations に fallback_message があれば、全文を新しいcreateへ回します。
stop_reason が refusal のときはcontinueしません。拒否されたターンを除いた(または言い換えた)会話で新しいcreateを始めます。SDK helperはこの扱いを自動で行います。
注意点・使えない機能
- 5分で切れる:最後のリクエストから5分で期限切れ、遅くとも1時間で削除。会話は必ず手元にも残す
- 料金は同じ:Claudeは毎回会話全体を読むので、トークン代もレート制限も変わらない
- 使えない機能:Message Batches、トークン数の計測、オンデマンドのコンパクション、多くのコンテキスト編集(clear_thinking の keep all を除く)。HIPAA readiness の組織と Inference hooks を有効にした組織も対象外
- 保存の扱い:暗号化してメモリ上だけで持ち、ディスクには書かない。ただしZDR(データを残さない契約)の対象外。ファイルは参照で持つため、スレッド利用中はファイルを消さない
- 一覧・取得・削除のAPIはない
- ストリーミング:応答idは message_start で来ますが、continueするのは message_stop のあと。途中で切れたcontinueの再送が thread_already_continued/thread_continue_in_flight なら、全文でreplayするのが安全
対象はすべてのモデル(ベータ)。Claude APIのほか、Claude Platform on AWS、Google Cloud(Anthropic管理)、Microsoft Foundryが対象です。
編集部の実測について(未実測)
2026年11月7日時点で、編集部の作業環境には Claude APIキー(ANTHROPIC_API_KEY)がありません。そのため、create/continueのリクエストサイズ差やTTFTの計測は行っていません。Claude Codeはログイン済みで、公式どおり多くの利用者ではスレッドが既定で有効とされますが、スレッドのオン/オフを切り替えて比べる手順や、リクエストサイズを安全に取る手段がこの環境では取れなかったため、体感速度のA/Bも未実測です。上の「約35%」はAnthropicのお知らせの中央値です。
よくある質問
Q. メッセージスレッドを使うと料金は安くなりますか?
安くなりません。送るデータは小さくなりますが、Claudeは毎回会話全体を読むため、トークン代とレート制限は今までと同じです。
Q. プロンプトキャッシュとは何が違いますか?
スレッドは「送る量」を減らし、プロンプトキャッシュは「読む部分の単価」を下げます。スレッドはキャッシュを自動で付けないので、両方使うならリクエストごとにキャッシュの指定(cache_control)を送ります。トップレベル指定はスレッドの全リクエストで同じ値にし、ブレークポイントは合計4つまでです。
Q. どれくらいの時間、会話を覚えていますか?
最後のリクエストから5分です。遅くとも1時間で削除されます。期限が切れたら、会話全体を送って新しいスレッドを作ります。
Q. どのモデル・どこで使えますか?
すべてのモデルでベータとして使えます。Claude APIのほか、Claude Platform on AWS、Google Cloud(Anthropic管理)、Microsoft Foundryが対象です。
Q. Claude Codeを使っているだけでも関係がありますか?
あります。Anthropicによると、Claude Codeの多くの利用者ではすでに既定で有効になっていて、長い作業で返答が始まるまでの時間が短くなります。
Q. thread_not_found が出たらどうすればよいですか?
手元に残した会話全体と system・tools を載せて、新しい create を送ります。原因(期限切れ、保存されなかったターン、別キーなど)は応答に書かれないため、同じAPIキーとワークスペースで通しているかも確認します。SDKのスレッド補助を使っている場合は、この作り直しを自動で1回行います。
Q. 途中のメッセージを編集したり、会話を要約して短くしたりできますか?
スレッドは追記のみなので、途中編集や分岐はできません。編集や要約後の内容で続けたいときは、その内容を通常のメッセージとして載せた新しい create でスレッドを作り直します。オンデマンドのコンパクションはスレッドと併用できません。
参考にした情報
2026年11月3日8:06(日本時間)に初回取得し、2026年11月7日14:08(日本時間)に再取得しました(いずれもHTTP 200)。最新の情報は各公式で確認してください。


