「batch processing」（バッチ処理）は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを1つずつ処理して即座にレスポンスを受け取る代わりに、バッチ処理では複数のリクエストをまとめて送信し、非同期で処理できます。このパターンは特に次のような場合に役立ちます。

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

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

Message Batches API

Message Batches APIは、大量のMessagesAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。リクエストを非同期で処理するための強力でコスト効率の高い方法です。このアプローチは即座のレスポンスを必要としないタスクに適しており、ほとんどのバッチは1時間以内に完了し、コストを50パーセント削減しながらスループットを向上させます。

このガイドに加えて、APIリファレンスを直接参照API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。することもできます。

Message Batches APIの仕組み

Message Batches APIにリクエストを送信すると、次のように処理されます。

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

これは、即座の結果を必要としない一括操作に特に役立ちます。例えば次のようなものです。

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

バッチの制限

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

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

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

バッチ化できるもの

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

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

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

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

料金

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

モデル	バッチトークン
名前	入力	出力
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$5 / MTok	$25 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work	$2 / MTok	$10 / MTok
Claude Sonnet 5.5The best combination of speed and intelligence	$1 / MTok	$5 / MTok
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	$0.05 / MTok100,000 トークン以下のプロンプトの場合	$0.25 / MTok
	$0.25 / MTok100,000 トークンを超えるプロンプトの場合	$1.25 / MTok
その他のモデル
Claude Mythos 5.1	$5 / MTok	$25 / MTok
Claude Fable 5	$5 / MTok	$25 / MTok
Claude Mythos 5	$5 / MTok	$25 / MTok
Claude Opus 5	$2.50 / MTok	$12.50 / 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	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 5	$1 / MTok	$5 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4.5	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.50 / MTok

Message Batches APIの使用方法

バッチの準備と作成

メッセージバッチは、Messageを作成するリクエストのリストで構成されます。個々のリクエストの構造は次のとおりです。

• Messagesリクエストを識別するための一意のcustom_idAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。。1〜64文字で、英数字、ハイフン、アンダースコアのみを含む必要があります（^[a-zA-Z0-9_-]{1,64}$に一致）。
• 標準のMessages APIAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。パラメータを含むparamsAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。オブジェクト

このリストをrequestsパラメータに渡すことで、バッチを作成API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。できます。

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-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

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

バッチが最初に作成されたとき、レスポンスの処理ステータスはin_progressです。

{
  "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
}

バッチの追跡

メッセージバッチのprocessing_statusAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。フィールドは、バッチがどの処理段階にあるかを示します。最初はin_progressで、バッチ内のすべてのリクエストの処理が完了して結果の準備ができるとendedに更新されます。バッチの状態は、Consoleにアクセスするか、取得エンドポイントを使用して監視できます。

メッセージバッチの完了をポーリングする

メッセージバッチをポーリングするには、そのidが必要です。これはバッチ作成時のレスポンス、またはバッチの一覧取得によって提供されます。処理が終了するまでバッチのステータスを定期的に確認するポーリングループを実装できます。

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)

すべてのメッセージバッチを一覧表示する

一覧エンドポイントAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。を使用して、ワークスペース内のすべてのメッセージバッチを一覧表示できます。APIはページネーションをサポートしており、必要に応じて追加のページを自動的に取得します。

client = anthropic.Anthropic()

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

バッチ結果の取得

バッチ処理が終了すると、バッチ内の各Messagesリクエストには結果が存在します。結果の種類は4つあります。

バッチのrequest_countsオブジェクトは、まだ処理中のリクエストと、各結果の種類ごとのリクエストの数をカウントします。

バッチの結果は、メッセージバッチのresults_urlAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。プロパティからダウンロードでき、組織の権限で許可されている場合はConsoleからもダウンロードできます。結果のサイズが大きくなる可能性があるため、一度にすべてをダウンロードするのではなく、結果をストリーミングAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。で取得することをお勧めします。

client = anthropic.Anthropic()

# 結果ファイルをメモリ効率の良いチャンクでストリーミングし、1件ずつ処理します
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    outcome = result.result
    match outcome.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if outcome.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}")

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

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","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-5-5","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は標準のエラー形式に設定されます。

バッチの結果には、バッチを作成したリクエストのAPIバージョンが使用されます。

メッセージバッチのキャンセル

キャンセルエンドポイントAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。を使用して、現在処理中のメッセージバッチをキャンセルできます。キャンセル直後、バッチのprocessing_statusはcancelingになります。前述と同じポーリング手法を使用して、キャンセルが確定するまで待つことができます。キャンセルされたバッチは最終的にendedのステータスになり、キャンセル前に処理されたリクエストの部分的な結果が含まれる場合があります。

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

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

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

{
  "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は「prompt caching」（プロンプトキャッシング）をサポートしており、バッチリクエストのコストと処理時間を削減できる可能性があります。プロンプトキャッシングとMessage Batchesの料金割引は重ねて適用できるため、両方の機能を併用するとさらに大きなコスト削減が得られます。ただし、バッチリクエストは非同期かつ並行して処理されるため、キャッシュヒットはベストエフォートで提供されます。ユーザーは通常、トラフィックパターンに応じて30パーセントから98パーセントのキャッシュヒット率を経験します。

バッチリクエストでキャッシュヒットの可能性を最大化するには、次のようにします。

1. バッチ内のすべてのMessageリクエストに同一のcache_controlブロックを含めます。
2. キャッシュエントリが5分間の有効期間後に期限切れにならないよう、リクエストを継続的に送信し続けます。
3. キャッシュされたコンテンツをできるだけ多く共有するようにリクエストを構成します。

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

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-5-5",
                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-5-5",
                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.",
                    }
                ],
            ),
        ),
    ]
)

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

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

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

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

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

拡張出力（ベータ）

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

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

1回の300kトークンの生成は完了までに1時間以上かかる場合があるため、24時間の処理期間を念頭に置いてバッチの送信を計画してください。標準のバッチ料金（標準API料金の50パーセント）が適用されます。

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-5-5",
                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)

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

Batches APIを効果的に使用するには、次のようにします。

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

よくある問題のトラブルシューティング

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

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

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

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

• ワークスペースの分離： バッチは作成されたワークスペース内で分離されます。同じワークスペース内のAPIリクエスト、またはConsoleでワークスペースのバッチを表示する権限を持つユーザーのみがアクセスできます。

• 結果の利用可能性： バッチの結果はバッチ作成後29日間利用でき、取得と処理のための十分な時間が確保されています。

よくある質問

利用可能状況

バッチ処理はすべてのモデルで利用可能です。

APIサポート

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

次のステップ