バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。即時レスポンスを伴う1件ずつの処理ではなく、バッチ処理では複数のリクエストをまとめて送信し、非同期で処理できます。このパターンは、特に以下のような場合に有用です。

大量のデータを処理する必要がある場合
即時のレスポンスが不要な場合
コスト効率を最適化したい場合
大規模な評価や分析を実行している場合

Message Batches APIは、このパターンのAnthropicによる最初の実装です。

この機能はZero Data Retention (ZDR)の対象外です。データは、この機能の標準的な保持ポリシーに従って保持されます。

Message Batches API

Message Batches APIは、大量のMessagesリクエストを非同期で処理するための強力かつコスト効率の高い方法です。このアプローチは即時レスポンスを必要としないタスクに適しており、ほとんどのバッチは1時間以内に完了し、コストを50%削減しながらスループットを向上させます。

このガイドに加えて、APIリファレンスを直接確認することもできます。

Message Batches APIの仕組み

Message Batches APIにリクエストを送信すると、以下の処理が行われます。

システムは、提供されたMessagesリクエストを含む新しいMessage Batchを作成します。
バッチは非同期で処理され、各リクエストは独立して処理されます。
バッチのステータスをポーリングし、すべてのリクエストの処理が終了したら結果を取得できます。

これは、即時の結果を必要としない一括操作に特に有用です。例えば以下のようなケースです。

大規模な評価：数千のテストケースを効率的に処理します。
コンテンツモデレーション：大量のユーザー生成コンテンツを非同期で分析します。
データ分析：大規模なデータセットに対するインサイトや要約を生成します。
一括コンテンツ生成：さまざまな目的（商品説明、記事要約など）のために大量のテキストを作成します。

バッチの制限事項

Message Batchは、100,000件のMessageリクエストまたは256 MBのサイズのいずれか先に到達した方に制限されます。
システムは各バッチを可能な限り高速に処理し、ほとんどのバッチは1時間以内に完了します。すべてのメッセージが完了した時点、または24時間経過後のいずれか早い方でバッチ結果にアクセスできます。24時間以内に処理が完了しない場合、バッチは期限切れになります。
バッチ結果は作成後29日間利用可能です。その後もバッチを表示することはできますが、結果はダウンロードできなくなります。
バッチはWorkspaceにスコープされます。APIキーが属するWorkspace内で作成されたすべてのバッチ（およびその結果）を表示できます。
レート制限は、Batches APIのHTTPリクエストと、処理待ちのバッチ内リクエスト数の両方に適用されます。Message Batches APIのレート制限を参照してください。さらに、現在の需要とリクエスト量に応じて処理が遅くなる場合があります。その場合、24時間後に期限切れになるリクエストが増える可能性があります。
高スループットかつ並行処理のため、バッチはWorkspaceに設定された支出上限をわずかに超える場合があります。
バッチ内の各リクエストは、max_tokensが少なくとも1である必要があります。max_tokens: 0（キャッシュの事前ウォーミング）はバッチ内ではサポートされていません。バッチ処理中に書き込まれた一時的なキャッシュエントリは、後続のリクエストが実行される前に期限切れになる可能性が高いためです。

サポートされているモデル

すべてのアクティブなモデルがMessage Batches APIをサポートしています。

バッチ処理できるもの

Messages APIに対して行えるほぼすべてのリクエストをバッチに含めることができます。これには以下が含まれます。

ビジョン
ツール使用（すべてのサーバーツール（ウェブ検索、ウェブフェッチ、コード実行、MCPコネクタ、アドバイザー、ツール検索）を含む）
システムメッセージ
マルチターン会話
拡張思考
ほとんどのベータ機能

バッチ内の各リクエストは独立して処理されるため、1つのバッチ内に異なるタイプのリクエストを混在させることができます。

少数のMessages APIパラメータは、バッチリクエストではサポートされていません。これらのいずれかを含めると、バリデーションエラーが返されます。

パラメータ	理由
`stream: true`	バッチ結果はストリームではなく、単一のファイルとして返されます。
`speed`（Fast mode）	Fast modeは同期レイテンシを調整するもので、非同期バッチ処理には適用されません。
`store` / `previous_thread_event_id`（Threads）	Threadsはステートフルですが、バッチリクエストはそうではありません。
`cache_hint` / `context_hint`	これらのルーティングヒントは同期リクエストのスケジューリングにのみ適用されます。
`max_tokens: 0`	バッチの制限事項を参照してください。
`research_preview_2026_02: "active"`	リサーチプレビューモードはバッチパスでは利用できません。

バッチの処理には5分以上かかる場合があるため、共有コンテキストを持つバッチを処理する際のキャッシュヒット率を向上させるために、プロンプトキャッシングで1時間のキャッシュ期間の使用を検討してください。

料金

Batches APIは大幅なコスト削減を提供します。すべての使用量は標準API価格の50%で課金されます。

モデル	バッチ入力	バッチ出力
Claude Fable 5	$5 / MTok	$25 / MTok
Claude Mythos 5（限定提供）	$5 / MTok	$25 / MTok
Claude Opus 4.8	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.7	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1（非推奨）	$7.50 / MTok	$37.50 / MTok
Claude Opus 4（Vertex AIを除き提供終了）	$7.50 / MTok	$37.50 / MTok

Message Batches APIの使用方法

バッチの準備と作成

Message Batchは、Messageを作成するためのリクエストのリストで構成されます。個々のリクエストの形式は以下で構成されます。

Messagesリクエストを識別するための一意のcustom_id。1〜64文字で、英数字、ハイフン、アンダースコアのみを含む必要があります（^[a-zA-Z0-9_-]{1,64}$に一致）。
標準のMessages APIパラメータを含むparamsオブジェクト

このリストをrequestsパラメータに渡すことでバッチを作成できます。

この例では、2つの別々のリクエストが非同期処理のためにまとめてバッチ化されています。各リクエストには一意のcustom_idがあり、Messages API呼び出しで使用する標準パラメータが含まれています。

Messages APIでバッチリクエストをテストする

各メッセージリクエストのparamsオブジェクトのバリデーションは非同期で実行され、バリデーションエラーはバッチ全体の処理が終了したときに返されます。まずMessages APIでリクエストの形式を検証することで、入力を正しく構築していることを確認できます。

バッチが最初に作成されると、レスポンスの処理ステータスはin_progressになります。

Output

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

バッチの追跡

Message Batchのprocessing_statusフィールドは、バッチの処理段階を示します。最初はin_progressで、バッチ内のすべてのリクエストの処理が完了し、結果が準備できるとendedに更新されます。Consoleにアクセスするか、取得エンドポイントを使用してバッチの状態を監視できます。

Message Batchの完了をポーリングする

Message Batchをポーリングするには、バッチ作成時のレスポンスまたはバッチ一覧で提供されるidが必要です。処理が終了するまでバッチステータスを定期的にチェックするポーリングループを実装できます。

すべてのMessage Batchの一覧表示

一覧エンドポイントを使用して、Workspace内のすべてのMessage Batchを一覧表示できます。APIはページネーションをサポートしており、必要に応じて追加のページを自動的に取得します。

バッチ結果の取得

バッチ処理が終了すると、バッチ内の各Messagesリクエストに結果が付与されます。結果タイプは4種類あります。

結果タイプ	説明
`succeeded`	リクエストは成功しました。メッセージ結果が含まれます。
`errored`	リクエストでエラーが発生し、メッセージは作成されませんでした。考えられるエラーには、無効なリクエストや内部サーバーエラーが含まれます。これらのリクエストには課金されません。
`canceled`	このリクエストがモデルに送信される前に、ユーザーがバッチをキャンセルしました。これらのリクエストには課金されません。
`expired`	このリクエストがモデルに送信される前に、バッチが24時間の有効期限に達しました。これらのリクエストには課金されません。

バッチのrequest_countsで結果の概要を確認できます。これは、これら4つの状態のそれぞれに到達したリクエスト数を示します。

バッチの結果は、Message Batchのresults_urlプロパティからダウンロードでき、組織の権限で許可されている場合はConsoleでも利用できます。結果のサイズが大きくなる可能性があるため、一度にすべてをダウンロードするのではなく、結果をストリーミングすることをお勧めします。

結果は.jsonl形式で、各行はMessage Batch内の単一リクエストの結果を表す有効なJSONオブジェクトです。ストリーミングされた各結果に対して、そのcustom_idと結果タイプに応じて異なる処理を行うことができます。以下は結果セットの例です。

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-8","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-8","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

結果にエラーがある場合、そのresult.errorは標準のエラー形式に設定されます。

バッチ結果は入力順序と一致しない場合があります

バッチ結果は任意の順序で返される可能性があり、バッチ作成時のリクエストの順序と一致しない場合があります。上記の例では、2番目のバッチリクエストの結果が1番目より先に返されています。結果を対応するリクエストと正しく照合するには、常にcustom_idフィールドを使用してください。

Message Batchのキャンセル

キャンセルエンドポイントを使用して、現在処理中のMessage Batchをキャンセルできます。キャンセル直後、バッチのprocessing_statusはcancelingになります。上記と同じポーリング手法を使用して、キャンセルが完了するまで待機できます。キャンセルされたバッチは最終的にendedステータスになり、キャンセル前に処理されたリクエストの部分的な結果が含まれる場合があります。

レスポンスには、canceling状態のバッチが表示されます。

Output

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Message Batchesでのプロンプトキャッシングの使用

Message Batches APIはプロンプトキャッシングをサポートしており、バッチリクエストのコストと処理時間を削減できる可能性があります。プロンプトキャッシングとMessage Batchesの料金割引は重複適用できるため、両方の機能を併用することでさらに大きなコスト削減が可能です。ただし、バッチリクエストは非同期かつ並行して処理されるため、キャッシュヒットはベストエフォートベースで提供されます。ユーザーは通常、トラフィックパターンに応じて30%から98%の範囲のキャッシュヒット率を経験します。

バッチリクエストでキャッシュヒットの可能性を最大化するには、以下を行ってください。

バッチ内のすべてのMessageリクエストに同一のcache_controlブロックを含める
キャッシュエントリが5分間の有効期間後に期限切れにならないよう、リクエストの安定したストリームを維持する
できるだけ多くのキャッシュコンテンツを共有するようにリクエストを構成する

バッチでプロンプトキャッシングを実装する例：

この例では、バッチ内の両方のリクエストに同一のシステムメッセージと、キャッシュヒットの可能性を高めるためにcache_controlでマークされた『高慢と偏見』の全文が含まれています。

サーバーツールとエージェントループ

すべてのサーバーツール（ウェブ検索、ウェブフェッチ、コード実行、MCPコネクタ、アドバイザー、ツール検索）はバッチリクエストで動作します。バッチワーカーは、同期Messages APIと同じサーバーサイドのエージェントループを実行します。

維持すべきオープンな接続がないため、バッチループはstop_reason: "pause_turn"を返す前に、同期リクエストよりもターンあたりより多くのイテレーションを実行します。バッチ結果がpause_turnで返された場合、そのターンは完了していません。pause_turn継続パターンに示されているとおり、一時停止したアシスタントコンテンツを後続のリクエスト（バッチまたは同期）で送信することで継続できます。

バッチワーカーはさらに、高度に並行したバッチ処理が組織のウェブ検索レート制限を使い果たさないように、組織ごとにweb_searchをスロットリングします。バッチはスロットリングされたリクエストを自動的に再試行するため、これを自分で処理する必要はありませんが、非常に大規模なウェブ検索バッチは完了までに時間がかかる場合があります。

拡張出力（ベータ）

output-300k-2026-03-24ベータヘッダーは、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、またはClaude Sonnet 4.6を使用するバッチリクエストのmax_tokens上限を300,000に引き上げます。このヘッダーを含めることで、標準の制限（モデルに応じて64kから128k）をはるかに超える出力を1ターンで生成できます。

拡張出力はMessage Batches APIでのみ利用可能で、同期Messages APIでは利用できません。Claude APIおよびAWS上のClaude Platformでサポートされており、現在Amazon Bedrock、Vertex AI、Microsoft Foundryでは利用できません。

拡張出力は、書籍規模の草稿や技術文書などの長文生成、網羅的な構造化データ抽出、大規模なコード生成スキャフォールド、長い推論チェーンなどに使用してください。

300kトークンの単一生成は完了までに1時間以上かかる場合があるため、24時間の処理ウィンドウを考慮してバッチ送信を計画してください。標準のバッチ料金（標準API価格の50%）が適用されます。

効果的なバッチ処理のベストプラクティス

Batches APIを最大限に活用するには、以下を行ってください。

バッチ処理ステータスを定期的に監視し、失敗したリクエストに対して適切な再試行ロジックを実装します。
順序が保証されないため、結果とリクエストを簡単に照合できるように意味のあるcustom_id値を使用します。
管理しやすくするために、非常に大きなデータセットを複数のバッチに分割することを検討します。
バリデーションエラーを回避するために、Messages APIで単一のリクエスト形式をドライランします。

一般的な問題のトラブルシューティング

予期しない動作が発生した場合は、以下を確認してください。

バッチリクエストの合計サイズが256 MBを超えていないことを確認します。リクエストサイズが大きすぎる場合、413 request_too_largeエラーが発生する可能性があります。
バッチ内のすべてのリクエストでサポートされているモデルを使用していることを確認します。
バッチ内の各リクエストに一意のcustom_idがあることを確認します。
バッチのcreated_at（処理のended_atではなく）時刻から29日未満であることを確認します。29日以上経過している場合、結果は表示できなくなります。
バッチがキャンセルされていないことを確認します。

バッチ内の1つのリクエストの失敗は、他のリクエストの処理に影響しないことに注意してください。

バッチストレージとプライバシー

Workspaceの分離：バッチは作成されたWorkspace内で分離されます。そのWorkspaceに関連付けられたAPIキー、またはConsoleでWorkspaceバッチを表示する権限を持つユーザーのみがアクセスできます。
結果の利用可能性：バッチ結果はバッチ作成後29日間利用可能で、取得と処理に十分な時間が確保されています。

データ保持

バッチ処理では、バッチ作成後最大29日間、リクエストとレスポンスのデータが保存されます。処理後はいつでもDELETE /v1/messages/batches/{batch_id}エンドポイントを使用してメッセージバッチを削除できます。進行中のバッチを削除するには、まずキャンセルしてください。非同期処理では、バッチの完了と結果の取得まで、入力と出力の両方をサーバーサイドで保存する必要があります。

すべての機能におけるZDR適格性については、APIとデータ保持を参照してください。

FAQ

次のステップ

検索結果

ソース帰属付きの検索結果を提供することで、RAGアプリケーションの自然な引用を可能にします。

プロンプトキャッシング

バッチ内のリクエスト間で共有されるプロンプトプレフィックスをキャッシュすることで、コストとレイテンシを削減します。

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

client = anthropic.Anthropic()

# 必要に応じて追加のページを自動的に取得します。
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

client = anthropic.Anthropic()

# 結果ファイルをメモリ効率の良いチャンクでストリーミングし、1件ずつ処理します
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # リクエストを再送信する前にリクエストボディを修正する必要があります
                print(f"Validation error {result.custom_id}")
            else:
                # リクエストはそのまま再試行できます
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                system=[
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Analyze the major themes in Pride and Prejudice.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                system=[
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Write a summary of Pride and Prejudice.",
                    }
                ],
            ),
        ),
    ]
)

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)

Message Batches API

Message Batches APIの仕組み

バッチの制限事項

サポートされているモデル

バッチ処理できるもの

料金

Message Batches APIの使用方法

バッチの準備と作成

バッチの追跡

Message Batchの完了をポーリングする

すべてのMessage Batchの一覧表示

バッチ結果の取得

Message Batchのキャンセル

Message Batchesでのプロンプトキャッシングの使用

サーバーツールとエージェントループ

拡張出力（ベータ）

効果的なバッチ処理のベストプラクティス

一般的な問題のトラブルシューティング

バッチストレージとプライバシー

データ保持

FAQ

バッチの処理にはどのくらい時間がかかりますか？

Batches APIはすべてのモデルで利用できますか？

Message Batches APIを他のAPI機能と併用できますか？

Message Batches APIは料金にどのように影響しますか？

送信後にバッチを更新できますか？

Message Batches APIにレート制限はありますか？また、Messages APIのレート制限と相互作用しますか？

バッチリクエストのエラーはどのように処理しますか？

次のステップ

Message Batches APIはプライバシーとデータ分離をどのように処理しますか？

Message Batches APIでプロンプトキャッシングを使用できますか？

Message Batches API

Message Batches APIの仕組み

バッチの制限事項

サポートされているモデル

バッチ処理できるもの

料金

Message Batches APIの使用方法

バッチの準備と作成

バッチの追跡

Message Batchの完了をポーリングする

すべてのMessage Batchの一覧表示

バッチ結果の取得

Message Batchのキャンセル

Message Batchesでのプロンプトキャッシングの使用

サーバーツールとエージェントループ

拡張出力（ベータ）

効果的なバッチ処理のベストプラクティス

一般的な問題のトラブルシューティング

バッチストレージとプライバシー

データ保持

FAQ

次のステップ