---
title: メッセージスレッド
url: https://platform.claude.com/docs/ja/build-with-claude/message-threads
description: 各リクエストで新しいメッセージのみを送信することで、長時間実行されるエージェントの最初のトークンまでの時間を、特に長い会話において短縮します。
featureMetadata:
  status: beta
  betaHeader: message-threads-2026-08-12
  zdr:
    eligibility: not-eligible
    note: スレッドの内容（会話、システムプロンプト、ツール）はメモリ内に保持され、サーバー管理の鍵で暗号化され、永続ストレージに書き込まれることはなく、スレッドの最後の使用から1時間以内に削除されます。この機能を使用しても、他のZDR適格機能の使用には影響しません。
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): beta
    Microsoft Foundry: beta
---

「message thread」（メッセージスレッド）を使用すると、リクエストは小さくなり、「time to first token」（最初のトークンまでの時間）は会話が長くなっても低く安定した状態に保たれます。スレッドは、長いエージェントループで最も役立ちます。スレッドがない場合、各ターンで会話全体が再度アップロードされ、APIはそのすべてを再度検証してトークン化します。スレッドを使用すると、その作業の大部分は新しいターンのみが対象になります。

「message thread」（メッセージスレッド）は、会話を短時間サーバー上に保持します。完全な会話を、システムプロンプトとツールとともに最初に一度送信します。以降の各ターンでは、新しいメッセージと前回のレスポンスの`id`のみを送信します。APIはモデルを呼び出す前に会話を再構築します。[Messages API](https://platform.claude.com/docs/ja/api/messages)リクエストに`thread`というパラメータを1つ追加するだけです。レスポンスは通常のメッセージです。

<Note>
  メッセージスレッドは、Claude Managed Agentsの[セッションスレッド](https://platform.claude.com/docs/ja/managed-agents/session-threads)とは異なります。
</Note>

## メッセージスレッドの仕組み

* **作成。** 現在と同じように、会話全体、`system`、`tools` を含めて最初のリクエストを送信し、`"thread": {"type": "create"}` を追加します。APIは、Claudeの返信を含む会話を、レスポンスの `id` の下に保存します。
* **継続。** 前回のレスポンス以降のメッセージのみを送信し、`"thread": {"type": "continue", "previous_message_id": "<previous id>"}` を追加します。`system` と `tools` はリクエストから除外してください。スレッドは作成リクエストの値を保持します。次のターンには、新しいレスポンスの `id` をそれぞれ使用します。
* **リプレイ。** スレッドはベストエフォートです。スレッドの有効期限は最後のリクエストから5分後に切れ、APIは最後の使用から1時間以内にスレッドを削除します。APIがレスポンスを保存するたびに、この5分間がリセットされます。APIがスレッドを継続できなくなった場合、継続リクエストは404エラーを返します。新しい作成リクエストで会話全体を再度送信し、そのレスポンスの `id` から継続してください。SDKのスレッドヘルパーは、このリプレイを自動的に行います（[SDKヘルパーの動作](https://platform.claude.com/docs/ja/build-with-claude/message-threads#sdk-helper-handles)を参照）。フォールバックモデルからのレスポンスの後については、[スレッドでフォールバックを使用する](https://platform.claude.com/docs/ja/build-with-claude/message-threads#fallbacks)を参照してください。

会話の信頼できる情報源（source of truth）は、引き続きアプリケーション側にあります。すべてのメッセージのコピーを独自に保持し、最初から[リプレイパス](https://platform.claude.com/docs/ja/build-with-claude/message-threads#recover)を構築してください。作成リクエストと 継続リクエストのどちらに対するレスポンスも、APIがそのターンを保存したかどうかを示しません。それが判明するのは次の 継続リクエストの時点です。SDKのスレッドヘルパーは、ヘルパーオブジェクトが存在する間このコピーをメモリ内に保持しますが、それ以外の場所には保存しません。会話をプロセスよりも長く存続させる必要がある場合は、独自のコピーを保持してください。

## SDKでスレッドを使用する

SDKには、スレッドリクエストを構築するスレッドヘルパーがあります。Messagesリクエストと同じフィールドで作成し、1ターンずつ送信します。ヘルパーは会話全体をメモリに保持します。

この例には2つのターンがあります。ヘルパーは最初のターンでスレッドを作成し、2番目のターンでそれを継続し、ベータヘッダーも自動的に追加します。トップレベルの`cache_control`はオプションです。これは各ターンでプロンプトキャッシングを要求します（[スレッドでのプロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/message-threads#prompt-caching)を参照）。これがない場合でも、以降の各ターンは新しいメッセージのみを送信しますが、自分でキャッシュブレークポイントを追加しない限り何もキャッシュされません。

<CodeGroup exclude="shell">
  ```python Python
  client = anthropic.Anthropic()

  # ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  thread = client.beta.messages.thread(
      model="claude-opus-5-5",
      max_tokens=1024,
      cache_control={"type": "ephemeral"},
      system="You are a support agent for Acme. Keep replies short.",
  )

  # ターン1: ヘルパーがスレッドを作成し、会話全体を送信します
  thread.send({"role": "user", "content": "Hi! I have a question about an order."})

  # ターン2: ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  const thread = client.beta.messages.thread({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    cache_control: { type: "ephemeral" },
    system: "You are a support agent for Acme. Keep replies short."
  });

  // ターン1：ヘルパーがスレッドを作成し、会話全体を送信します
  await thread.send({ role: "user", content: "Hi! I have a question about an order." });

  // ターン2：ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  const second = await thread.send({
    role: "user",
    content: "How long does standard shipping usually take?"
  });

  for (const block of second.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }
  ```

  ```csharp C#
  using Anthropic.Helpers.Beta;

  AnthropicClient client = new();

  // ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  var thread = client.Beta.Messages.Thread(
      new ThreadCreateParams
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages = [],
          CacheControl = new(),
          System = "You are a support agent for Acme. Keep replies short.",
      }
  );

  // ターン1：ヘルパーがスレッドを作成し、会話全体を送信します
  await thread.Send(
      new BetaUserMessageParam { Content = "Hi! I have a question about an order." }
  );

  // ターン2：ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  var second = await thread.Send(
      new BetaUserMessageParam { Content = "How long does standard shipping usually take?" }
  );

  foreach (var block in second.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  // ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  thread := client.Beta.Messages.NewThread(anthropic.BetaMessageThreadCreateParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
  	System: []anthropic.BetaTextBlockParam{
  		{Text: "You are a support agent for Acme. Keep replies short."},
  	},
  })

  // ターン1：ヘルパーがスレッドを作成し、会話全体を送信します
  _, err := thread.Send(ctx, anthropic.BetaMessageThreadSendParams{
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hi! I have a question about an order.")),
  	},
  })
  if err != nil {
  	panic(err)
  }

  // ターン2：ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  second, err := thread.Send(ctx, anthropic.BetaMessageThreadSendParams{
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("How long does standard shipping usually take?")),
  	},
  })
  if err != nil {
  	panic(err)
  }

  for _, block := range second.Content {
  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  var client = AnthropicOkHttpClient.fromEnv();

  // ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  var thread = client.beta().messages().thread(
      ThreadCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(BetaCacheControlEphemeral.builder().build())
          .system("You are a support agent for Acme. Keep replies short.")
          .build()
  );

  // ターン1: ヘルパーがスレッドを作成し、会話全体を送信します
  thread.send("Hi! I have a question about an order.");

  // ターン2: ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  var second = thread.send("How long does standard shipping usually take?");

  second.content().stream()
      .flatMap(block -> block.text().stream())
      .forEach(textBlock -> IO.println(textBlock.text()));
  ```

  ```php PHP
  $client = new Client();

  // ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  $thread = $client->beta->messages->thread(
      maxTokens: 1024,
      model: Model::CLAUDE_OPUS_5_5,
      cacheControl: new BetaCacheControlEphemeral,
      system: 'You are a support agent for Acme. Keep replies short.',
  );

  // ターン1: ヘルパーがスレッドを作成し、会話全体を送信します
  $thread->send(['role' => 'user', 'content' => 'Hi! I have a question about an order.']);

  // ターン2: ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  $second = $thread->send(['role' => 'user', 'content' => 'How long does standard shipping usually take?']);

  foreach ($second->content as $block) {
      if ($block instanceof BetaTextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # ヘルパーを作成します。この呼び出しではリクエストは送信されません。
  thread = client.beta.messages.thread(
    model: :"claude-opus-5-5",
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    system_: "You are a support agent for Acme. Keep replies short."
  )

  # ターン1: ヘルパーがスレッドを作成し、会話全体を送信します
  thread.send_message({role: "user", content: "Hi! I have a question about an order."})

  # ターン2: ヘルパーがスレッドを継続し、新しいメッセージのみを送信します
  second = thread.send_message({role: "user", content: "How long does standard shipping usually take?"})

  second.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## `thread`フィールドを自分で送信する

cURL、CLI、またはSDKの通常の`create`メソッドなどを使用してスレッドリクエストを自分で構築するには、各リクエストに`thread`フィールドを追加します。

スレッドのすべてのリクエストで`message-threads-2026-08-12`ベータヘッダーを送信してください。

この例では、最初のターンでスレッドを作成し、2番目のターンでそれを継続します。トップレベルの`cache_control`は各ターンでプロンプトキャッシングを要求します。これは、会話が[キャッシュ可能な最小長](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)より長くなった時点で有効になります。

<CodeGroup>
  ```bash cURL
  # ターン1: 会話全体を送信してスレッドを作成します
  curl -sS --fail-with-body 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-opus-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"}
    }'

  # ターン2: 新しいメッセージのみを送信します。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: 2023-06-01" \
    -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": "How long does standard shipping usually take?"}],
      "thread": {"type": "continue", "previous_message_id": "'"$message_id"'"}
    }'
  ```

  ```bash CLI
  # ターン1: 会話全体を送信してスレッドを作成します
  ant beta:messages create --beta message-threads-2026-08-12 <<'YAML'
  model: claude-opus-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
  YAML

  # ターン2: 新しいメッセージのみを送信します。message_id にはターン1のレスポンスの id を設定します。
  # system と tools は省略します。スレッドがそれらを保持します。
  ant beta:messages create --beta message-threads-2026-08-12 <<YAML
  model: claude-opus-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: $message_id
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  # ターン1: 会話全体を送信してスレッドを作成します
  first = client.beta.messages.create(
      model="claude-opus-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"},
      betas=["message-threads-2026-08-12"],
  )

  # ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  # systemとtoolsは省略します。スレッドがそれらを保持します。
  second = client.beta.messages.create(
      model="claude-opus-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": first.id},
      betas=["message-threads-2026-08-12"],
  )

  for block in second.content:
      if block.type == "text":
          print(block.text)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // ターン1: 会話全体を送信してスレッドを作成します
  const first = await client.beta.messages.create({
    model: "claude-opus-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" },
    betas: ["message-threads-2026-08-12"]
  });

  // ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  // system と tools は省略します。スレッドがそれらを保持します。
  const second = await client.beta.messages.create({
    model: "claude-opus-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: first.id },
    betas: ["message-threads-2026-08-12"]
  });

  for (const block of second.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  // ターン1: 会話全体を送信してスレッドを作成します
  var first = await client.Beta.Messages.Create(
      new()
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          CacheControl = new(),
          System = "You are a support agent for Acme. Keep replies short.",
          Messages =
          [
              new BetaUserMessageParam { Content = "Hi! I have a question about an order." },
          ],
          Thread = new BetaThreadCreateParams(),
          Betas = [AnthropicBeta.MessageThreads2026_08_12],
      }
  );

  // ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  // System と Tools は省略します。スレッドがそれらを保持しています。
  var second = await client.Beta.Messages.Create(
      new()
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          CacheControl = new(),
          Messages =
          [
              new BetaUserMessageParam { Content = "How long does standard shipping usually take?" },
          ],
          Thread = new BetaThreadContinueParams(first.ID),
          Betas = [AnthropicBeta.MessageThreads2026_08_12],
      }
  );

  foreach (var block in second.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  // ターン1: 会話全体を送信してスレッドを作成します
  threadCreate := anthropic.NewBetaThreadCreateParams()
  first, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
  	System: []anthropic.BetaTextBlockParam{
  		{Text: "You are a support agent for Acme. Keep replies short."},
  	},
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hi! I have a question about an order.")),
  	},
  	Thread: anthropic.BetaMessageThreadParamUnion{OfCreate: &threadCreate},
  	Betas:  []anthropic.AnthropicBeta{anthropic.AnthropicBetaMessageThreads2026_08_12},
  })
  if err != nil {
  	panic(err)
  }

  // ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  // System と Tools は省略します。スレッドがそれらを保持します。
  second, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("How long does standard shipping usually take?")),
  	},
  	Thread: anthropic.BetaMessageThreadParamOfContinue(first.ID),
  	Betas:  []anthropic.AnthropicBeta{anthropic.AnthropicBetaMessageThreads2026_08_12},
  })
  if err != nil {
  	panic(err)
  }

  for _, block := range second.Content {
  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  var client = AnthropicOkHttpClient.fromEnv();

  // ターン1: 会話全体を送信してスレッドを作成します
  var first = client.beta().messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(BetaCacheControlEphemeral.builder().build())
          .system("You are a support agent for Acme. Keep replies short.")
          .addUserMessage("Hi! I have a question about an order.")
          .thread(BetaThreadCreateParams.builder().build())
          .addBeta(AnthropicBeta.MESSAGE_THREADS_2026_08_12)
          .build()
  );

  // ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  // system と tools は省略します。スレッドがそれらを保持しています。
  var second = client.beta().messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(BetaCacheControlEphemeral.builder().build())
          .addUserMessage("How long does standard shipping usually take?")
          .continueThread(first.id())
          .addBeta(AnthropicBeta.MESSAGE_THREADS_2026_08_12)
          .build()
  );

  second.content().stream()
      .flatMap(block -> block.text().stream())
      .forEach(textBlock -> IO.println(textBlock.text()));
  ```

  ```php PHP
  $client = new Client();

  // ターン1: 会話全体を送信してスレッドを作成します
  $first = $client->beta->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      cacheControl: new BetaCacheControlEphemeral,
      system: 'You are a support agent for Acme. Keep replies short.',
      messages: [
          ['role' => 'user', 'content' => 'Hi! I have a question about an order.'],
      ],
      thread: BetaThreadCreateParams::with(),
      betas: ['message-threads-2026-08-12'],
  );

  // ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  // systemとtoolsは省略します。スレッドがそれらを保持します。
  $second = $client->beta->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      cacheControl: new BetaCacheControlEphemeral,
      messages: [
          ['role' => 'user', 'content' => 'How long does standard shipping usually take?'],
      ],
      thread: BetaThreadContinueParams::with(previousMessageID: $first->id),
      betas: ['message-threads-2026-08-12'],
  );

  foreach ($second->content as $block) {
      if ($block instanceof BetaTextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # ターン1: 会話全体を送信してスレッドを作成します
  first = client.beta.messages.create(
    model: :"claude-opus-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"},
    betas: ["message-threads-2026-08-12"]
  )

  # ターン2: 新しいメッセージとターン1のレスポンスのidのみを送信します。
  # system_ と tools は省略します: スレッドがそれらを保持します。
  second = client.beta.messages.create(
    model: :"claude-opus-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: first.id},
    betas: ["message-threads-2026-08-12"]
  )

  second.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## 各リクエストで送信するもの

| グループ  | フィールド                                                                                                                                                                      | ルール                                                                                                                |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 作成時のみ | `system`、`tools`                                                                                                                                                           | 作成リクエストでのみ、それらに付ける`cache_control`ブレークポイントとともに送信します。継続リクエストでいずれかを送信すると、`null`であっても400エラーが返されます。                     |
| 固定    | `model`、`tool_choice`、`thinking`、`mcp_servers`（各サーバーの認可トークンを除く）、`context_management`、`output_config`、`container`内の`skills`、トップレベルの`cache_control`、および`anthropic-beta`値のセット | スレッドのすべてのリクエストで、作成リクエストと同じ値で送信します。異なる値を送信すると、コード`thread_fingerprint_mismatch`の400エラーが返され、エラーメッセージには異なるフィールドが示されます。 |
| 自由    | `max_tokens`、`stop_sequences`、`stream`、`metadata`、`service_tier`、およびこのページで言及されていないその他のフィールド                                                                                | これらはターンごとに変更できます。                                                                                                  |

APIは、MCPサーバーのURL、MCP認可トークン、またはコンテナの`id`を保存しません。`mcp_servers`と`container`は、それらを使用するすべてのリクエストで送信してください。MCP認可トークンはリクエスト間で変更できます。

SDKのスレッドヘルパーは、継続リクエストから `system` と `tools` を自動的に除外し、固定フィールドを毎ターン再送信します。

[サーバーサイドフォールバック](https://platform.claude.com/docs/ja/build-with-claude/refusals-and-fallback#server-side-fallback)を使用する場合は、`fallbacks`フィールドをスレッドのすべてのリクエストで送信するか、まったく送信しないかのどちらかにしてください。[スレッドでフォールバックを使用する](https://platform.claude.com/docs/ja/build-with-claude/message-threads#fallbacks)を参照してください。

作成時のみのフィールドまたは固定フィールドを変更するには、新しいスレッドを開始します。新しい値を指定した作成リクエストで完全な会話を送信してください。

Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Sonnet 5.5、Claude Haiku 5.5では、`system`または`tools`を変更すると、会話内にすでにある`thinking`ブロックと`redacted_thinking`ブロックが無効になり、作成リクエストが400エラーを返す可能性があります。これを回避するには、送信する会話からすべての`thinking`ブロックと`redacted_thinking`ブロックを除外してください。その場合、モデルは以前の推論なしで応答します。[編集とみなされるもの](https://platform.claude.com/docs/ja/build-with-claude/preserved-thinking#what-counts-as-an-edit)、[`prefix_mismatch_behavior`が未設定の場合](https://platform.claude.com/docs/ja/build-with-claude/preserved-thinking#enforcement)、および[無効なブロックに対するAPIの処理](https://platform.claude.com/docs/ja/build-with-claude/preserved-thinking#mismatch-behavior)を参照してください。

継続リクエストでは新しいメッセージのみを送信してください。APIは、それらをすでに保持しているメッセージと照合しません。再送信したメッセージは会話内に2回現れる可能性があり、またはリクエストがエラーを返す可能性があります。たとえば、前回のレスポンスで始まる継続リクエストはエラーを返します。

新しいメッセージは通常 `user` メッセージで始まります。これは次のユーザーターン、または前回のレスポンスの `tool_use` に応答する `tool_result` ブロックです。レスポンスが [`stop_reason: "pause_turn"`](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#pause-turn) で停止した場合は、そのレスポンスの `id` からの継続リクエストと空の `messages` リスト（`"messages": []`）で再開してください。そのリクエストが404エラーを返した場合は、一時停止したレスポンスを含む会話全体を新しい作成リクエストでリプレイしてください。ターンが一時停止している間は新しい `user` メッセージを送信しないでください。APIはそれを拒否します。SDKのスレッドヘルパーでは、メッセージなしで `send()` (go, csharp: `Send()`; ruby: `send_message()`) を呼び出してください。ヘルパーがこのリクエストを送信し、404エラーの場合はリプレイします。

スレッドは追記専用であり、各レスポンスの`id`は一度だけ継続できます。常にスレッドの最新のレスポンス`id`から継続してください。以前のメッセージを編集または分岐させる場合は、作成リクエストで新しいスレッドを開始してください。以前のターンを要約に置き換える場合は、[会話をコンパクションする](https://platform.claude.com/docs/ja/build-with-claude/message-threads#compaction)を参照してください。

## スレッドでのプロンプトキャッシング

スレッドはプロンプトを自動的にキャッシュしません。[プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)はスレッドがない場合と同じように動作します。キャッシュブレークポイントの配置場所は自分で選択します。

各ターンをキャッシュするには、前述の例のように、スレッドのすべてのリクエストでトップレベルの`cache_control`を送信してください。APIはこれを、各リクエストの`messages`のうちキャッシュ可能な最後のブロックに適用します。これにより、各ターンは以前の会話をキャッシュから読み取り、新しいターンをキャッシュに書き込みます。トップレベルの`cache_control`は固定フィールドです。すべてのリクエストで同じ値を送信してください。

ブロックに`cache_control`ブレークポイントを自分で配置することもできます：

* 作成リクエストで送信したブレークポイントは、`tools`、`system`、または最後のメッセージブロックより前のメッセージブロックに置かれている場合、以降のすべてのターンで引き続き機能します。リクエストの `messages` の最後のブロックに置かれたブレークポイントは、そのリクエストでキャッシュを書き込みます。新しいターンごとにキャッシュするには、すべてのリクエストでブレークポイントを送信してください。ブレークポイントのないリクエストでも、会話の一部をキャッシュから読み取る場合があります。
* 継続リクエストでは以前のメッセージを再送信できないため、送信後にブレークポイントを移動または削除することはできません。
* `thread` を含むリクエストには、最大4つの `cache_control` ブレークポイントを含めることができます。トップレベルの `cache_control` は1つとしてカウントされます。作成リクエストの `system` と `tools` にあるブレークポイントは、継続リクエストのたびに再度カウントされます。保存済みの以前のメッセージにあるブレークポイントはカウントされません。ブレークポイントが1つでも多すぎると、コード `thread_unsupported_request` を含む400エラーが返されます。
* メッセージブロックに自分でブレークポイントを配置する場合は、新しい 作成リクエストで会話をリプレイする際に以前のメッセージからブレークポイントを削除し、最後のブロックに1つ残して、リクエストが4つの上限内に収まるようにしてください。

## ストリーミング

スレッドは[ストリーミング](https://platform.claude.com/docs/ja/build-with-claude/streaming)で動作します。レスポンスの`id`は`message_start`イベントで届きますが、そこから継続するのは`message_stop`イベントを受信した後にしてください。それより前に送信された継続リクエストは404エラーを返す可能性があります。

継続リクエストのストリームが`message_stop`の前に切断された場合は、同じ継続リクエストを再度送信してください。そのリクエストが`thread_already_continued`または`thread_continue_in_flight`エラーを返した場合は、新しい作成リクエストで完全な会話をリプレイしてください。

サーバーがまだレスポンスを生成している間、またはサーバーがそれを保存した後に、接続が切断された可能性があります。そのため、APIは再試行を拒否することがあります。リプレイは常に安全です。

SDKのスレッドヘルパーは、ストリームが切断された後に継続リクエストを再試行しません。[SDKヘルパーの動作](https://platform.claude.com/docs/ja/build-with-claude/message-threads#sdk-helper-handles)を参照してください。

## スレッドを継続できない場合の復旧

APIがスレッドを継続できない場合、継続リクエストは`error.details.error_code`が`thread_not_found`に設定された404エラーを返します。レスポンスは理由を示しません。原因には次のものがあります：

* スレッドの有効期限が切れた。
* APIが前のターンを提供したが、保存しなかった。たとえば、APIは`max_tokens`によって途中で切れたツール呼び出しで終わるレスポンスを保存しません。
* フォールバックモデルが前回のレスポンスを書いた。[スレッドでフォールバックを使用する](https://platform.claude.com/docs/ja/build-with-claude/message-threads#fallbacks)を参照してください。
* 前回のレスポンスがまだ生成中である。
* リクエストが異なる組織またはワークスペースから送信された。
* リクエストが、スレッドを作成したものとは異なるユーザーまたはサービスアカウントから送信された。[ワークスペースキー（レガシー）](https://platform.claude.com/docs/ja/manage-claude/authentication#key-types)で作成されたスレッドはそのキーに紐づくため、スレッド全体で同じキーを使用してください。
* 新しいメッセージが、保存された会話が受け入れられないものを追加している。たとえば、画像がなかった会話に最初の画像を追加すると、このエラーが返される場合があります。

復旧するには、手元のコピーから会話全体を、`system` と `tools` を含めて新しい作成リクエストで送信します。SDKのスレッドヘルパーはこの作成リクエストを自動的に一度送信し、その際に以前のターンの `cache_control` ブレークポイントを省略します。コピー内の以前のメッセージに `cache_control` ブレークポイントが含まれている場合は、先にそれらを削除してください（[スレッドでのプロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/message-threads#prompt-caching)を参照）。その後、新しいレスポンスの `id` から継続します。フォールバックモデルが前のレスポンスを作成した場合は、[スレッドでフォールバックを使用する](https://platform.claude.com/docs/ja/build-with-claude/message-threads#fallbacks)を参照してください。所有権に関する原因を排除するには、スレッドのすべてのリクエストで同じAPIキーとワークスペースを使用してください。Claude Platform on AWSでは、スレッドのすべてのリクエストに、そのスレッドを作成したIAMロールまたはIAMユーザーの認証情報で署名してください。

存在しないモデルへのリクエストも404エラーを返すため、リプレイする前に`error.details.error_code`を確認してください。

リプレイ直後の継続リクエストが依然として404エラーを返す場合、APIがその会話（たとえば非常に大きな会話）を保存できない可能性があります。`thread` なしで送信してください。SDKのスレッドヘルパーは、`unsupported_request_behavior` (typescript, java, php: `unsupportedRequestBehavior`; go, csharp: `UnsupportedRequestBehavior`) を `continue_unthreaded` (ruby: `:continue_unthreaded`; java: `CONTINUE_UNTHREADED`; csharp: `ContinueUnthreaded`; go: `BetaMessageThreadUnsupportedRequestBehaviorContinueUnthreaded`) に設定して作成した場合にこれを行います。それ以外の場合は、ターンごとにリプレイします。

### 拒否の後

レスポンスに `stop_reason: "refusal"` がある場合は、スレッドを継続しないでください。APIはすでに拒否されたターンを保持している可能性があり、継続リクエストではそれを削除できません。拒否の原因となったターンを省略するか言い換えた作成リクエストで、新しいスレッドを開始してください。[拒否とフォールバック](https://platform.claude.com/docs/ja/build-with-claude/refusals-and-fallback)を参照してください。SDKのスレッドヘルパーはこれを自動的に行います。拒否されたターンを保持せず、次のターンで新しいスレッドを開始します。

### スレッドでフォールバックを使用する

[サーバーサイドフォールバック](https://platform.claude.com/docs/ja/build-with-claude/refusals-and-fallback#server-side-fallback)は、Claude APIでスレッドとともに利用できます。スレッドの作成時に決定してください。`fallbacks`をスレッドのすべてのリクエストで送信するか、まったく送信しないかです。`fallbacks`の値はリクエスト間で変更できます。`fallbacks`を追加または削除する継続リクエストは、コード`thread_fingerprint_mismatch`の400エラーを返します。

スレッドは1つのモデルを保持するため、APIはフォールバックモデルが書いたターンを保存しません。レスポンスは通常どおり受け取れますが、その`id`から継続することはできません。各レスポンスの後、次の手順に従ってください：

1. `stop_reason` が `"refusal"` の場合は、[拒否の後](https://platform.claude.com/docs/ja/build-with-claude/message-threads#after-a-refusal)に従ってください。

2. それ以外の場合は、`usage.iterations` 内の `fallback_message` エントリを探します。ストリームでは、最後の `message_delta` イベントから読み取ります。エントリがない場合は、通常どおりスレッドを継続します。

3. 存在する場合、そのレスポンスはフォールバックモデルが作成したものです。そのレスポンスと次のメッセージを含む会話全体を、新しい作成リクエストで送信します。そのリクエストには `server-side-fallback-2026-07-01` ベータヘッダーを付けたままにしてください。次の2つのリクエストのいずれかを選択します。

   * **同じリクエストをもう一度送信する。** `model`、`fallbacks`、およびその他のパラメータはそのままにします。リクエストしたモデルが応答した場合、APIは新しいスレッドを保存します。フォールバックモデルが応答した場合、レスポンスには再び `fallback_message` エントリが含まれ、APIはそれを保存しないため、次のターンでこの手順を繰り返します。[スティッキールーティング](https://platform.claude.com/docs/ja/build-with-claude/refusals-and-fallback#sticky-routing)によってこれらのリクエストがフォールバックモデルに直接送られる場合があるため、毎ターン会話全体を送信することになる可能性があります。SDKのスレッドヘルパーはこの方法で動作します。
   * **フォールバックモデルで新しいスレッドを開始する。** `model` をその `fallback_message` エントリ内の `model` に設定し、`fallbacks` を省略して、このモデルが受け付けるパラメータを使用します。APIはこのスレッドを即座に保存し、スレッドはフォールバックモデル上に留まります。フォールバックの試行は送信した設定とは異なる設定で実行された可能性があるため、最初のリクエストからコピーした値をAPIが拒否する場合があります。

4. そのリクエストへのレスポンスを使って手順1に戻ります。レスポンスに `fallback_message` エントリがない場合は、その `id` から新しいスレッドを継続します。

[スティッキールーティング](https://platform.claude.com/docs/ja/build-with-claude/refusals-and-fallback#sticky-routing)は、リクエストがフォールバックした後（作成リクエスト、または `thread` を含まないリクエスト）に開始されます。約1時間の間、`fallbacks` を含む同じ会話に対する後続の作成リクエストを、リクエストしたモデルを試さずにフォールバックモデルへ直接送る場合があります。APIはそれらのターンをいずれも保存せず、応答があるたびにその1時間がリセットされます。継続リクエストがこのルーティングを開始することはなく、このルーティングを使用することもありません。組織またはワークスペースがゼロデータ保持または顧客管理の暗号化キーを使用している場合、スティッキールーティングは適用されません。

## 会話をコンパクションする

スレッドは追記専用であるため、以前のターンを要約に置き換えることはできません。会話をコンパクションするには、要約から新しいスレッドを開始してください。要約はコード内で作成し、`system` と `tools` を含めた新しい作成リクエストで、通常のメッセージとして送信してください。[オンデマンドコンパクション](https://platform.claude.com/docs/ja/build-with-claude/compaction-on-demand)はスレッドでは利用できません（[スレッドがサポートしていない機能](https://platform.claude.com/docs/ja/build-with-claude/message-threads#unsupported)を参照）。

## SDKヘルパーの動作

ヘルパーが行うこと：

* スレッドを使用するすべてのリクエストに `message-threads-2026-08-12` ベータヘッダーを追加します。
* 最初のターンでスレッドを作成し、その後はスレッドを継続します。その際、新しいメッセージのみを送信し、`system` と `tools` は省略します。
* 継続リクエストが `thread_not_found`、`thread_already_continued`、または `thread_continue_in_flight` を返した場合、新しい作成リクエストで会話全体を一度リプレイします。
* メッセージなしで `send()` (go, csharp: `Send()`; ruby: `send_message()`) を呼び出すと、`pause_turn` レスポンスを再開します。
* 拒否の後に新しいスレッドを開始します。`stop_reason: "refusal"` レスポンスは通常どおり受け取りますが、ヘルパーはそのターンを保持しません。その呼び出しに渡したメッセージを取り消します。`thread.append(...)` (csharp, go: `thread.Append(...)`; php: `$thread->append(...)`) で追加したメッセージや、ヘルパーの作成時に渡したメッセージは、ステージされたまま残ります。次のターンでは、それらを拒否されたターンより前の会話とともに、新しい作成リクエストで送信します。言い換えたメッセージを送信するか、ステージされたメッセージが拒否の原因となった場合は、そのメッセージを除いたparamsから新しいスレッドを開始してください。
* フォールバックモデルからのレスポンスの後は、新しい作成リクエストを送信します。レスポンスの `usage.iterations` に `fallback_message` エントリがある場合、ヘルパーはそのレスポンスを保持し、次のターンで会話全体を新しい作成リクエストで送信します。404エラーを待つことはありません。そのリクエストでは、設定した `model` と `fallbacks` が維持されます。
* 以前のターンを再度送信する際（たとえばリプレイ時やフォークの最初のターン）には、それらのターンの `cache_control` ブレークポイントを省略します。最新のメッセージ、`system`、`tools`、およびトップレベルの `cache_control` は、指定したとおりに送信されます。

自分で処理すること：

* **フォールバック。** APIがフォールバックモデルから応答し続けている間、APIはそれらのターンを一切保存しないため、ヘルパーは毎ターン会話全体を新しい作成リクエストで送信します。リクエストしたモデルからのレスポンスを受け取った後は、継続リクエストに戻ります。代わりに会話をフォールバックモデルに移行するには、[スレッドでフォールバックを使用する](https://platform.claude.com/docs/ja/build-with-claude/message-threads#fallbacks)のように、その `model` を指定し `fallbacks` を含めずに、paramsから新しいスレッドを開始してください。
* **中断されたストリーム。** レスポンスの途中でストリームが終了した場合、ヘルパーは完了したブロックと受信済みのテキストを保持し、次のターンで会話全体を新しい作成リクエストで送信します。ヘルパーは自動的にリトライしません。代わりに中断されたターンを再送するには、メッセージなしで `send()` (go, csharp: `Send()`; ruby: `send_message()`) を呼び出してください。保持された部分がツール呼び出しで終わっている場合は、次のメッセージでそれらに応答してください。ストリームが `stop_reason: "refusal"` を示した後に読み取りを停止した場合、ヘルパーはそのターンを拒否として扱います。
* **その他のエラー。** `thread_fingerprint_mismatch` および `thread_unsupported_request` エラーはコードに返されます。`thread_unsupported_request` エラーの後に `thread` なしで続行するには、`unsupported_request_behavior` (typescript, java, php: `unsupportedRequestBehavior`; go, csharp: `UnsupportedRequestBehavior`) を `continue_unthreaded` (ruby: `:continue_unthreaded`; java: `CONTINUE_UNTHREADED`; csharp: `ContinueUnthreaded`; go: `BetaMessageThreadUnsupportedRequestBehaviorContinueUnthreaded`) に設定してヘルパーを作成してください。この設定では、リプレイ後の最初の継続リクエストが再び `thread_not_found` を返した場合にも、ヘルパーは `thread` の使用を停止します。APIがその会話を保存できない可能性があります。この設定がない場合、ヘルパーはターンごとにリプレイします。独自のスレッドを作成するツールランナーは、デフォルトでこの設定を使用します。

SDKのベータ版ツールランナーもデフォルトでスレッドを使用しますが、ランナーの作成時にオフにできます。

### その他のヘルパーメソッド

| 目的                      | 使用するもの                                                                                                                                                                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ターンをストリーミングする           | `thread.stream(...)` (csharp: `thread.SendStreaming(...)`; go: `thread.SendStreaming(ctx, params)`; java: `thread.sendStreaming(...)`; php: `$thread->sendStream(...)`)                                                                                                                                                              |
| ストリーミングされたターンの完了したレスポンス | `stream.get_final_message()` (typescript: `stream.finalMessage()`; csharp: `thread.LastMessage`; go: `thread.LastMessage()`; java: `thread.lastMessage()`; php: `$thread->lastMessage()`; ruby: `stream.accumulated_message`)                                                                                                        |
| 会話全体                    | `thread.messages` (csharp: `thread.Messages`; go: `thread.Messages()`; java: `thread.messages()`; php: `$thread->messages()`)                                                                                                                                                                                                        |
| 次のターンの継続元となるレスポンスの `id` | `thread.previous_message_id` (typescript: `thread.previousMessageId`; csharp: `thread.PreviousMessageID`; go: `thread.PreviousMessageID()`; java: `thread.previousMessageId()`; php: `$thread->previousMessageId()`)                                                                                                                 |
| 送信せずにメッセージを追加する         | `thread.append(...)` (csharp, go: `thread.Append(...)`; php: `$thread->append(...)`)                                                                                                                                                                                                                                                 |
| 以降のターンのフィールドを変更する       | `thread.update(...)` (csharp: `thread.Update(p => p with { ... })`; go: `thread.Params.MaxTokens = ...`; java: `thread.update(b -> ...)`; php: `$thread->update([...])`)                                                                                                                                                             |
| スレッドをコピーする              | `thread.fork()` (csharp, go: `thread.Fork()`; php: `$thread->fork()`; ruby: `thread.fork`)                                                                                                                                                                                                                                           |
| 新しいスレッドを開始するためのフィールドと会話 | `thread.params` (csharp, go: `thread.Params`; java: `thread.params()`; php: `$thread->params()`)                                                                                                                                                                                                                                     |
| このスレッド上のツールランナー         | `thread.tool_runner()` (typescript, java: `thread.toolRunner()`; csharp: `thread.ToolRunner(tools)`; go: `thread.NewToolRunner(tools)`; php: `$thread->toolRunner()`; ruby: `thread.tool_runner`)                                                                                                                                    |
| スレッドを使用しないツールランナー       | `tool_runner(..., thread=False)` (typescript: `toolRunner({ ..., thread: false })`; csharp: `ToolRunner(parameters, tools, thread: false)`; go: `BetaToolRunnerParams{DisableThread: true}`; java: `ToolRunnerCreateParams.builder().thread(false)`; php: `toolRunner(..., thread: false)`; ruby: `tool_runner(..., thread: false)`) |

**ストリーミング。** ヘルパーはストリームが`message_stop`に到達した時点でレスポンスを記録するため、ストリームを最後まで読み取ってください。途中で読み取りを停止する場合は、スレッドが次のターンで使用できるようにストリームを終了してください：

* Python：`with`ブロックを抜けます。
* TypeScript：ループを抜けるか、`abort()`を呼び出します。
* Go：`Close`を呼び出します。
* JavaとRuby：`close()`を呼び出します。
* C#：列挙子を破棄します。`await foreach`を抜けるとこれが行われます。
* PHP：`close()`を呼び出します。

C#では、ストリームの読み取りを開始した時点でリクエストが送信されます。

C#、Go、Java、PHPでは、拒否の後も `thread.LastMessage` (go: `thread.LastMessage()`; java: `thread.lastMessage()`; php: `$thread->lastMessage()`) は前のターンのレスポンスを返し、最初のターンでは何も返しません。拒否はストリームのイベントから読み取ってください。

**フィールドの変更。** updateは何も送信せず、以降のすべてのターンに適用されます。スレッドにレスポンスがある場合、ヘルパーは`system`または`tools`を変更するターンを拒否し、APIはその他の固定フィールドの変更を拒否します（[各リクエストで送信するもの](https://platform.claude.com/docs/ja/build-with-claude/message-threads#what-to-send)を参照）。これらのフィールドのいずれかを変更するには、paramsから新しいスレッドを開始するか、スレッドをフォークして最初のターンの前にフォークを更新してください。

**フォーク。** フォークは会話、フィールド、リクエストオプションをコピーし、何も送信しません。最初のターンでは新しい作成リクエストで完全な会話を送信し、その後2つのスレッドは独立します。フォークは常に会話全体から開始し、以前のレスポンスからは開始しません。

**Params。** paramsには、ヘルパーのフィールドと会話全体が保持されます。新しいスレッドを開始するには、これらをヘルパーを作成するメソッドに渡します。たとえば、異なる`system`を使用する場合（[各リクエストで送信するもの](https://platform.claude.com/docs/ja/build-with-claude/message-threads#what-to-send)を参照）や、後のターンを削除するために`messages`を切り詰める場合です。paramsから開始したスレッドは、`cache_control`ブレークポイントを含め、すべてのメッセージを指定したとおりに送信するため、上限の4以内に収めてください（[スレッドでのプロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/message-threads#prompt-caching)を参照）。Rubyを除き、paramsにはリクエストオプションが含まれないため、それらを再度渡してください。

**構造化出力。** ヘルパーの作成時に出力形式を指定します。後のターンで変更することはできません。解析結果の取得方法はSDKによって異なります。

* PythonとTypeScript：`thread.parse(...)` を呼び出します。
* C#：`client.Beta.Messages.Thread<T>(...)` でヘルパーを作成します。
* Go：`Send` は、`Params.OutputConfig.Format.Schema` が指す構造体にアンマーシャルします。
* Java：`thread(...)` と `outputConfig(MyClass.class)` でヘルパーを作成します。
* PHP：`outputConfig` がモデルクラスを指定している場合、`send()` はテキストブロックに `parsed` を設定します。
* Ruby：`output_config: {format: MyModel}` を `thread(...)` に渡し、`reply.parsed_output` を読み取ります。

## エラー

APIは、この表のエラーをモデルの実行前に返します。リクエストはトークンを使用せず、スレッドとその有効期限は変更されません。`error.type`は、400エラーの場合は`invalid_request_error`、404エラーの場合は`not_found_error`です。

| ステータス | `error_code`                  | 意味                                                                                  | 対処方法                                                        |
| ----- | ----------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| 404   | `thread_not_found`            | APIがスレッドを継続できません。                                                                   | 新しい作成リクエストで完全な会話を送信します。                                     |
| 400   | `thread_fingerprint_mismatch` | 固定フィールドが、スレッドとともに保存された値と異なります。エラーメッセージにフィールドが示されます。                                 | 固定フィールドを同じに保つか、変更する場合は新しいスレッドを開始します。                        |
| 400   | `thread_already_continued`    | 各レスポンスの`id`は一度だけ継続できます。                                                             | スレッドの最新のレスポンス`id`から継続します。クライアントがそのレスポンスを受信していない場合は、リプレイします。 |
| 400   | `thread_continue_in_flight`   | このレスポンス`id`からの別の継続リクエストがまだ実行中です。これは通常、自分自身の以前の試行です。                                 | それが完了するのを待ってそのレスポンス`id`から継続するか、リプレイします。                     |
| 400   | `thread_unsupported_request`  | リクエストが、スレッドでサポートされていない機能または組織設定を使用しています。存在する場合、`error.details.unsupported`がそれを示します。 | リクエストからその機能を削除するか、`thread`なしで完全な会話を送信します。                   |

スレッドリクエストに対する一部の400エラーには`error_code`が含まれません。たとえば、`previous_message_id`のない継続リクエストや、`system`または`tools`を含む継続リクエストです。

次の例はエラー本文を示しています：

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
```

## スレッドがサポートしていない機能

スレッドは次の機能をサポートしていません：

* [Message Batches](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)。`thread`を含むリクエスト項目は、バッチ結果で`invalid_request_error`として終了します。
* [トークンカウント](https://platform.claude.com/docs/ja/build-with-claude/token-counting)。`thread`を含むトークンカウントリクエストは400エラーを返します。代わりに、`system`と`tools`を含む完全な会話をカウントしてください。
* [コンパクション](https://platform.claude.com/docs/ja/build-with-claude/compaction)。[オンデマンドコンパクション](https://platform.claude.com/docs/ja/build-with-claude/compaction-on-demand)はスレッドでは利用できません。`thread`を含むリクエストは、`compaction`パラメータを設定した場合、または`compact-2026-09-04`ベータヘッダーとともに`compaction`ブロックを送信した場合に、400エラーを返します。[会話をコンパクションする](https://platform.claude.com/docs/ja/build-with-claude/message-threads#compaction)を参照してください。
* [コンテキスト編集](https://platform.claude.com/docs/ja/build-with-claude/context-editing)。ただし、`keep: "all"`を指定した`clear_thinking_20251015`を除きます。
* [HIPAA対応](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention#hipaa-readiness)が有効になっている組織。
* [Inference hooks](https://platform.claude.com/docs/ja/manage-claude/inference-hooks)がオンになっている組織。

APIは、スレッドがサポートしていないほとんどのリクエストを、コード`thread_unsupported_request`の400エラーで拒否します。`error.details.unsupported`が存在する場合、そこには次のいずれかの値が含まれます：

| 値                    | 意味                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `context_management` | リクエストが、スレッドでサポートされていないコンテキスト管理またはコンパクションを使用しています。                                                                                                            |
| `cache_control`      | リクエストに4つを超える`cache_control`ブレークポイントがあります。[スレッドでのプロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/message-threads#prompt-caching)を参照してください。 |
| `fallbacks`          | リクエストが`fallbacks`を設定していますが、組織はスレッドで`fallbacks`を使用できません。                                                                                                      |
| `hipaa`              | 組織でHIPAA対応が有効になっています。                                                                                                                                        |
| `inference_hooks`    | 組織でInference hooksがオンになっています。                                                                                                                                |

APIはこのリストに値を追加する場合があります。認識できない値を受け取った場合は、`thread`なしで完全な会話を送信してください。これらの条件の複数に該当するリクエストは、そのうち1つのみを示すエラーを受け取ります。

## 制限事項

* スレッドを一覧表示、読み取り、または削除するAPIはありません。
* スレッドは、Claude API、[Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws)、 Claude Models on Google Cloud (Anthropic managed)、および[Claude in Microsoft Foundry](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry)で利用できます。

## 料金とレート制限

スレッドは料金や[レート制限](https://platform.claude.com/docs/ja/api/rate-limits)を変更しません。

## データ保持

メッセージスレッドは「Zero Data Retention」（ゼロデータ保持）、すなわちZDRの対象となりません。この機能の使用は、ZDRの対象となる他の機能の使用に影響を与えません。APIはスレッドをサーバー管理のキーで暗号化してメモリ内に保持し、永続ストレージには一切書き込まず、最後の使用から1時間以内に削除します。

スレッドは、APIがモデルに送信する会話、作成リクエストの`system`と`tools`、および以降のリクエストのチェックに使用する固定フィールドのフィンガープリントを保持します。ファイルは参照によって保持されるため、スレッドを使用している間は、会話で使用するすべてのファイルを利用可能な状態に保ってください。

すべての機能にわたるZDRの対象については、[APIとデータ保持](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention)を参照してください。

## 関連項目

* [プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)
* [ストリーミング](https://platform.claude.com/docs/ja/build-with-claude/streaming)
* [エラー](https://platform.claude.com/docs/ja/api/errors)

## 利用可能状況

メッセージスレッドはすべてのモデルでベータ版です。

### APIサポート

#### [Messages API](https://platform.claude.com/docs/ja/build-with-claude/working-with-messages)

* 利用可能状況：利用可能

| ステータス | クラウドプラットフォーム                                                                                                                                                                                                                                                                                                                                                                           |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ベータ   | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry) |

### 必須のベータヘッダー

[ベータヘッダーの概要](https://platform.claude.com/docs/ja/api/beta-headers)

ベータヘッダーを使用すると、実験的な機能や新しいモデル機能が標準APIに組み込まれる前にアクセスできます。

* `message-threads-2026-08-12`

### データの取り扱い

[データの取り扱いの概要](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention#feature-eligibility)

| 項目    | ゼロデータ保持                                                                                                                                                                                                                         | HIPAA |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| ステータス | 対象外                                                                                                                                                                                                                             | 対象外   |
| 詳細    | スレッドの内容（会話、システムプロンプト、ツール）はメモリ内に保持され、サーバー管理の鍵で暗号化され、永続ストレージに書き込まれることはなく、スレッドの最後の使用から1時間以内に削除されます。この機能を使用しても、他のZDR適格機能の使用には影響しません。 [詳細はこちら](https://platform.claude.com/docs/ja/build-with-claude/message-threads#data-retention) | —     |

対象エンドポイント：

* `/v1/messages` `thread`を指定した場合