„Batch processing“ (Batch-Verarbeitung) ist ein leistungsstarker Ansatz, um große Mengen von Anfragen effizient zu bearbeiten. Anstatt Anfragen einzeln mit sofortigen Antworten zu verarbeiten, ermöglicht dir die Batch-Verarbeitung, mehrere Anfragen gemeinsam zur asynchronen Verarbeitung einzureichen. Dieses Muster ist besonders nützlich, wenn:

• Du große Datenmengen verarbeiten musst
• Sofortige Antworten nicht erforderlich sind
• Du auf Kosteneffizienz optimieren möchtest
• Du groß angelegte Evaluierungen oder Analysen durchführst

Die Message Batches API ist Anthropics erste Implementierung dieses Musters.

Message Batches API

Die Message Batches API ist eine leistungsstarke, kosteneffiziente Möglichkeit, große Mengen von Messages-Anfragen asynchron zu verarbeiten. Dieser Ansatz eignet sich gut für Aufgaben, die keine sofortigen Antworten erfordern, wobei die meisten Batches in weniger als 1 Stunde abgeschlossen werden, während die Kosten um 50 % gesenkt und der Durchsatz erhöht wird.

Zusätzlich zu diesem Leitfaden kannst du die API-Referenz direkt erkunden.

So funktioniert die Message Batches API

Wenn du eine Anfrage an die Message Batches API sendest:

1. Das System erstellt einen neuen Message Batch mit den bereitgestellten Messages-Anfragen.
2. Der Batch wird dann asynchron verarbeitet, wobei jede Anfrage unabhängig bearbeitet wird.
3. Du kannst den Status des Batches abfragen und die Ergebnisse abrufen, sobald die Verarbeitung aller Anfragen beendet ist.

Dies ist besonders nützlich für Massenoperationen, die keine sofortigen Ergebnisse erfordern, wie zum Beispiel:

• Groß angelegte Evaluierungen: Verarbeite Tausende von Testfällen effizient.
• Inhaltsmoderation: Analysiere große Mengen nutzergenerierter Inhalte asynchron.
• Datenanalyse: Generiere Erkenntnisse oder Zusammenfassungen für große Datensätze.
• Massenhafte Inhaltserstellung: Erstelle große Textmengen für verschiedene Zwecke (zum Beispiel Produktbeschreibungen, Artikelzusammenfassungen).

Batch-Einschränkungen

• Ein Message Batch ist auf entweder 100.000 Message-Anfragen oder 256 MB Größe begrenzt, je nachdem, was zuerst erreicht wird.
• Das System verarbeitet jeden Batch so schnell wie möglich, wobei die meisten Batches innerhalb von 1 Stunde abgeschlossen werden. Du kannst auf die Batch-Ergebnisse zugreifen, wenn alle Nachrichten abgeschlossen sind oder nach 24 Stunden, je nachdem, was zuerst eintritt. Batches laufen ab, wenn die Verarbeitung nicht innerhalb von 24 Stunden abgeschlossen wird.
• Batch-Ergebnisse sind 29 Tage nach der Erstellung verfügbar. Danach kannst du den Batch weiterhin ansehen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
• Batches sind auf einen Workspace beschränkt. Du kannst alle Batches (und deren Ergebnisse) einsehen, die innerhalb des Workspace erstellt wurden, in dem deine Anfrage ausgeführt wird.
• „Rate limits“ (Ratenlimits) gelten sowohl für HTTP-Anfragen an die Batches API als auch für die Anzahl der Anfragen innerhalb eines Batches, die auf Verarbeitung warten. Siehe Ratenlimits der Message Batches API. Darüber hinaus kann die Verarbeitung je nach aktueller Nachfrage und deinem Anfragevolumen verlangsamt werden. In diesem Fall kann es vorkommen, dass mehr Anfragen nach 24 Stunden ablaufen.
• Aufgrund des hohen Durchsatzes und der gleichzeitigen Verarbeitung können Batches das konfigurierte Ausgabenlimit deines Workspace geringfügig überschreiten.
• Jede Anfrage in einem Batch muss einen max_tokens-Wert von mindestens 1 haben. max_tokens: 0 (Cache-Vorwärmen) wird innerhalb eines Batches nicht unterstützt, da ein während der Batch-Verarbeitung geschriebener ephemerer Cache-Eintrag wahrscheinlich ablaufen würde, bevor die Folgeanfrage ausgeführt wird.

Unterstützte Modelle

Alle aktiven Modelle unterstützen die Message Batches API.

Was in Batches verarbeitet werden kann

Nahezu jede Anfrage, die du an die Messages API stellen kannst, kann in einen Batch aufgenommen werden. Dazu gehören:

• Vision
• „Tool use“ (Tool-Nutzung), einschließlich aller Server-Tools (Websuche, Web-Abruf, Codeausführung, MCP-Konnektoren, Advisor und Tool-Suche)
• System-Nachrichten
• Mehrstufige Konversationen
• „Extended thinking“ (erweitertes Nachdenken)
• Die meisten Beta-Funktionen

Da jede Anfrage im Batch unabhängig verarbeitet wird, kannst du verschiedene Arten von Anfragen innerhalb eines einzelnen Batches mischen.

Eine kleine Anzahl von Messages-API-Parametern wird in Batch-Anfragen nicht unterstützt. Wenn du einen davon angibst, wird ein Validierungsfehler zurückgegeben:

Preise

Die Batches API bietet erhebliche Kosteneinsparungen. Die gesamte Nutzung wird zu 50 % der Standard-API-Preise abgerechnet.

Model	Batch tokens
Name	Input	Output
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 4.5The fastest model with near-frontier intelligence	$0.50 / MTok	$2.50 / MTok
Additional models
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 3.5	$0.40 / MTok	$2 / MTok

So verwendest du die Message Batches API

Deinen Batch vorbereiten und erstellen

Ein Message Batch besteht aus einer Liste von Anfragen zum Erstellen einer Message. Die Form einer einzelnen Anfrage umfasst:

• Eine eindeutige custom_id zur Identifizierung der Messages-Anfrage. Muss 1 bis 64 Zeichen lang sein und darf nur alphanumerische Zeichen, Bindestriche und Unterstriche enthalten (entsprechend ^[a-zA-Z0-9_-]{1,64}$).
• Ein params-Objekt mit den Standardparametern der Messages API

Du kannst einen Batch erstellen, indem du diese Liste im Parameter requests übergibst:

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)

In diesem Beispiel werden zwei separate Anfragen gemeinsam zur asynchronen Verarbeitung in einem Batch zusammengefasst. Jede Anfrage hat eine eindeutige custom_id und enthält die Standardparameter, die du für einen Messages-API-Aufruf verwenden würdest.

Wenn ein Batch erstmals erstellt wird, hat die Antwort den Verarbeitungsstatus 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
}

Deinen Batch verfolgen

Das Feld processing_status des Message Batch gibt an, in welcher Verarbeitungsphase sich der Batch befindet. Es beginnt mit in_progress und wird auf ended aktualisiert, sobald alle Anfragen im Batch fertig verarbeitet wurden und die Ergebnisse bereitstehen. Du kannst den Zustand deines Batches überwachen, indem du die Console besuchst oder den Abruf-Endpunkt verwendest.

Abfragen des Abschlusses eines Message Batch

Um einen Message Batch abzufragen, benötigst du seine id, die in der Antwort beim Erstellen eines Batches oder beim Auflisten von Batches bereitgestellt wird. Du kannst eine Polling-Schleife implementieren, die den Batch-Status regelmäßig überprüft, bis die Verarbeitung beendet ist:

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)

Alle Message Batches auflisten

Du kannst alle Message Batches in deinem Workspace über den List-Endpunkt auflisten. Die API unterstützt Paginierung und ruft bei Bedarf automatisch weitere Seiten ab:

client = anthropic.Anthropic()

# Ruft bei Bedarf automatisch weitere Seiten ab.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Batch-Ergebnisse abrufen

Sobald die Batch-Verarbeitung beendet ist, hat jede Messages-Anfrage im Batch ein Ergebnis. Es gibt vier Ergebnistypen:

Die request_counts des Batches zeigen eine Übersicht deiner Ergebnisse und geben an, wie viele Anfragen jeden dieser vier Zustände erreicht haben.

Die Ergebnisse des Batches stehen unter der Eigenschaft results_url des Message Batch zum Download bereit und, sofern die Organisationsberechtigung dies zulässt, in der Console. Aufgrund der potenziell großen Größe der Ergebnisse wird empfohlen, die Ergebnisse zu streamen, anstatt sie alle auf einmal herunterzuladen.

client = anthropic.Anthropic()

# Ergebnisdatei speichereffizient in Chunks streamen und einzeln verarbeiten
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":
                # Request-Body muss vor dem erneuten Senden korrigiert werden
                print(f"Validation error {result.custom_id}")
            else:
                # Request kann direkt erneut gesendet werden
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

Die Ergebnisse liegen im .jsonl-Format vor, wobei jede Zeile ein gültiges JSON-Objekt ist, das das Ergebnis einer einzelnen Anfrage im Message Batch darstellt. Für jedes gestreamte Ergebnis kannst du abhängig von seiner custom_id und seinem Ergebnistyp etwas anderes tun. Hier ist ein Beispielsatz von Ergebnissen:

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

Wenn dein Ergebnis einen Fehler enthält, wird sein result.error auf die standardmäßige Fehlerform gesetzt.

Einen Message Batch abbrechen

Du kannst einen Message Batch, der gerade verarbeitet wird, über den Cancel-Endpunkt abbrechen. Unmittelbar nach dem Abbruch ist der processing_status eines Batches canceling. Du kannst dieselbe zuvor beschriebene Polling-Technik verwenden, um zu warten, bis der Abbruch abgeschlossen ist. Abgebrochene Batches enden mit dem Status ended und können Teilergebnisse für Anfragen enthalten, die vor dem Abbruch verarbeitet wurden.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

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

Die Antwort zeigt den Batch im Zustand 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
}

Prompt-Caching mit Message Batches verwenden

Die Message Batches API unterstützt Prompt-Caching, wodurch du potenziell Kosten und Verarbeitungszeit für Batch-Anfragen reduzieren kannst. Die Preisnachlässe von Prompt-Caching und Message Batches können kombiniert werden, was zu noch größeren Kosteneinsparungen führt, wenn beide Funktionen zusammen verwendet werden. Da Batch-Anfragen jedoch asynchron und gleichzeitig verarbeitet werden, werden Cache-Treffer nach dem Best-Effort-Prinzip bereitgestellt. Nutzer erzielen typischerweise Cache-Trefferquoten zwischen 30 % und 98 %, abhängig von ihren Traffic-Mustern.

Um die Wahrscheinlichkeit von Cache-Treffern in deinen Batch-Anfragen zu maximieren:

1. Füge identische cache_control-Blöcke in jede Message-Anfrage innerhalb deines Batches ein.
2. Halte einen stetigen Strom von Anfragen aufrecht, um zu verhindern, dass Cache-Einträge nach ihrer 5-minütigen Lebensdauer ablaufen.
3. Strukturiere deine Anfragen so, dass sie möglichst viel gecachten Inhalt gemeinsam nutzen.

Beispiel für die Implementierung von Prompt-Caching in einem 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-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.",
                    }
                ],
            ),
        ),
    ]
)

In diesem Beispiel enthalten beide Anfragen im Batch identische System-Nachrichten und den vollständigen Text von „Stolz und Vorurteil“, markiert mit cache_control, um die Wahrscheinlichkeit von Cache-Treffern zu erhöhen.

Server-Tools und die agentische Schleife

Alle Server-Tools (Websuche, Web-Abruf, Codeausführung, MCP-Konnektoren, Advisor und Tool-Suche) funktionieren in Batch-Anfragen. Der Batch-Worker führt dieselbe serverseitige agentische Schleife aus wie die synchrone Messages API.

Da keine offene Verbindung aufrechterhalten werden muss, führt die Batch-Schleife mehr Iterationen pro Turn aus als eine synchrone Anfrage, bevor sie stop_reason: "pause_turn" zurückgibt. Wenn ein Batch-Ergebnis mit pause_turn zurückkommt, wurde der Turn nicht abgeschlossen; du kannst ihn fortsetzen, indem du den pausierten Assistant-Inhalt in einer Folgeanfrage (Batch oder synchron) einreichst, genau wie im pause_turn-Fortsetzungsmuster gezeigt.

Der Batch-Worker drosselt zusätzlich web_search pro Organisation, damit eine hochgradig gleichzeitige Batch-Verarbeitung das Websuche-Ratenlimit deiner Organisation nicht ausschöpft. Der Batch wiederholt gedrosselte Anfragen automatisch; du musst dies nicht selbst handhaben, aber sehr große Websuche-Batches können länger bis zum Abschluss benötigen.

Erweiterte Ausgabe (Beta)

Der Beta-Header output-300k-2026-03-24 erhöht die max_tokens-Obergrenze auf 300.000 für Batch-Anfragen mit 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 oder Claude Sonnet 4.6. Füge den Header hinzu, um in einem einzigen Turn Ausgaben zu generieren, die weit über das Standardlimit von 128k max_tokens hinausgehen.

Verwende die erweiterte Ausgabe für die Generierung langer Inhalte wie Entwürfe in Buchlänge und technische Dokumentation, umfassende strukturierte Datenextraktion, große Codegenerierungs-Gerüste und lange Argumentationsketten.

Eine einzelne Generierung mit 300k Token kann über eine Stunde dauern, plane deine Batch-Einreichungen daher mit Blick auf das 24-Stunden-Verarbeitungsfenster. Es gelten die Standard-Batch-Preise (50 % der Standard-API-Preise).

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)

Best Practices für effektives Batching

Um das Beste aus der Batches API herauszuholen:

• Überwache den Batch-Verarbeitungsstatus regelmäßig und implementiere eine geeignete Wiederholungslogik für fehlgeschlagene Anfragen.
• Verwende aussagekräftige custom_id-Werte, um Ergebnisse leicht den Anfragen zuzuordnen, da die Reihenfolge nicht garantiert ist.
• Erwäge, sehr große Datensätze zur besseren Handhabbarkeit in mehrere Batches aufzuteilen.
• Führe einen Probelauf einer einzelnen Anfrageform mit der Messages API durch, um Validierungsfehler zu vermeiden.

Fehlerbehebung bei häufigen Problemen

Bei unerwartetem Verhalten:

• Überprüfe, dass die Gesamtgröße der Batch-Anfrage 256 MB nicht überschreitet. Wenn die Anfrage zu groß ist, erhältst du möglicherweise einen 413-Fehler request_too_large.
• Prüfe, dass du für alle Anfragen im Batch unterstützte Modelle verwendest.
• Stelle sicher, dass jede Anfrage im Batch eine eindeutige custom_id hat.
• Stelle sicher, dass seit dem created_at-Zeitpunkt des Batches (nicht dem ended_at-Zeitpunkt der Verarbeitung) weniger als 29 Tage vergangen sind. Wenn mehr als 29 Tage vergangen sind, sind die Ergebnisse nicht mehr einsehbar.
• Vergewissere dich, dass der Batch nicht abgebrochen wurde.

Beachte, dass das Fehlschlagen einer Anfrage in einem Batch die Verarbeitung anderer Anfragen nicht beeinflusst.

Batch-Speicherung und Datenschutz

• Workspace-Isolation: Batches sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Auf sie kann nur durch API-Anfragen in demselben Workspace oder durch Nutzer mit der Berechtigung zum Anzeigen von Workspace-Batches in der Console zugegriffen werden.

• Verfügbarkeit der Ergebnisse: Batch-Ergebnisse sind 29 Tage nach Erstellung des Batches verfügbar, was ausreichend Zeit für Abruf und Verarbeitung lässt.

Datenaufbewahrung

Die Batch-Verarbeitung speichert Anfrage- und Antwortdaten bis zu 29 Tage nach der Batch-Erstellung. Du kannst einen Message Batch jederzeit nach der Verarbeitung über den Endpunkt DELETE /v1/messages/batches/{batch_id} löschen. Um einen laufenden Batch zu löschen, brich ihn zuerst ab. Die asynchrone Verarbeitung erfordert die serverseitige Speicherung sowohl der Eingaben als auch der Ausgaben bis zum Abschluss des Batches und dem Abruf der Ergebnisse.

Zur ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenaufbewahrung.

FAQ

Nächste Schritte