„Batch processing" (Batch-Verarbeitung) ist ein leistungsstarker Ansatz, um große Mengen von Anfragen effizient zu verarbeiten. Anstatt Anfragen einzeln mit sofortigen Antworten zu verarbeiten, ermöglicht dir die Batch-Verarbeitung, mehrere Anfragen zusammen für die asynchrone 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, kostengünstige 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.



Wie die Message Batches API funktioniert

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 behandelt wird.
3. Du kannst den Status des Batches abfragen und die Ergebnisse abrufen, sobald die Verarbeitung für alle Anfragen abgeschlossen 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 von nutzergenerierten Inhalten asynchron.
• Datenanalyse: Generiere Erkenntnisse oder Zusammenfassungen für große Datensätze.
• Massenerstellung von Inhalten: Erstelle große Mengen an Text für verschiedene Zwecke (z. B. 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 anzeigen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
• Batches sind auf einen Workspace beschränkt. Du kannst alle Batches (und ihre Ergebnisse) anzeigen, die innerhalb des Workspace erstellt wurden, zu dem dein API-Key gehört.
• 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. Zusätzlich 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 leicht überschreiten.
• Jede Batch-Anfrage muss max_tokens von mindestens 1 haben. max_tokens: 0 (Cache-Vorwärmung) wird innerhalb eines Batches nicht unterstützt, da ein flüchtiger Cache-Eintrag, der während der Batch-Verarbeitung geschrieben wird, wahrscheinlich abläuft, bevor die Folgeanfrage ausgeführt wird.



Unterstützte Modelle

Alle aktiven Modelle unterstützen die Message Batches API.



Was in einem Batch verarbeitet werden kann

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

• Vision
• Tool-Nutzung, einschließlich aller Server-Tools (Websuche, Web-Fetch, Code-Ausführung, MCP-Konnektoren, Advisor und Tool-Suche)
• Systemnachrichten
• Mehrstufige Konversationen
• Erweitertes Denken
• Die meisten Beta-Features

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. Das Einbeziehen eines dieser Parameter führt zu einem Validierungsfehler:



Preise

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



So verwendest du die Message Batches API



Bereite deinen Batch vor und erstelle ihn

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

• Einer eindeutigen 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}$).
• Einem params-Objekt mit den Standard-Parametern der Messages API

Du kannst einen Batch erstellen, indem du diese Liste an den requests-Parameter ü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-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)

In diesem Beispiel werden zwei separate Anfragen für die asynchrone Verarbeitung 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 zum ersten Mal 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
}



Verfolge deinen Batch

Das Feld processing_status des Message Batch gibt an, in welcher Verarbeitungsphase sich der Batch befindet. Es beginnt mit in_progress und wechselt dann zu ended, sobald alle Anfragen im Batch verarbeitet wurden und die Ergebnisse bereit sind. Du kannst den Status deines Batches überwachen, indem du die Console besuchst oder den Abruf-Endpunkt verwendest.



Polling auf Abschluss des 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 abgeschlossen 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 mit dem 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 abgeschlossen ist, hat jede Messages-Anfrage im Batch ein Ergebnis. Es gibt 4 Ergebnistypen:

Du siehst eine Übersicht deiner Ergebnisse mit den request_counts des Batches, die zeigen, 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 zur Verfügung und, sofern die Organisationsberechtigung dies zulässt, auch 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()

# Streame die Ergebnisdatei in speichereffizienten Chunks und verarbeite sie einzeln
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":
                # Request-Body muss vor dem erneuten Senden der Anfrage korrigiert werden
                print(f"Validation error {result.custom_id}")
            else:
                # Anfrage kann direkt wiederholt 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 je nach custom_id und 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-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}}}}

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



Einen Message Batch abbrechen

Du kannst einen Message Batch, der gerade verarbeitet wird, mit dem Cancel-Endpunkt abbrechen. Unmittelbar nach dem Abbruch ist der processing_status eines Batches canceling. Du kannst dieselbe oben beschriebene Polling-Technik verwenden, um zu warten, bis der Abbruch abgeschlossen ist. Abgebrochene Batches haben am Ende den 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 noch größere Kosteneinsparungen ermöglicht, wenn beide Features zusammen verwendet werden. Da Batch-Anfragen jedoch asynchron und gleichzeitig verarbeitet werden, werden Cache-Treffer nach dem Best-Effort-Prinzip bereitgestellt. Nutzer erleben typischerweise Cache-Trefferraten 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 so viel gecachten Inhalt wie möglich teilen

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

In diesem Beispiel enthalten beide Anfragen im Batch identische Systemnachrichten 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-Fetch, Code-Ausfü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 die hochgradig gleichzeitige Batch-Verarbeitung das Websuche-Ratenlimit deiner Organisation nicht erschöpft. Der Batch wiederholt gedrosselte Anfragen automatisch; du musst dies nicht selbst handhaben, aber sehr große Websuche-Batches können länger dauern, bis sie abgeschlossen sind.



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 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 oder Claude Sonnet 4.6. Füge den Header hinzu, um Ausgaben zu generieren, die weit über dem Standardlimit (64k bis 128k je nach Modell) in einem einzigen Turn liegen.

Verwende die erweiterte Ausgabe für die Generierung langer Texte wie buchlange Entwürfe und technische Dokumentation, umfassende strukturierte Datenextraktion, große Code-Generierungs-Gerüste und lange Argumentationsketten.

Eine einzelne 300k-Token-Generierung kann über eine Stunde dauern, plane deine Batch-Einreichungen also 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-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)



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 einfach mit Anfragen abzugleichen, da die Reihenfolge nicht garantiert ist.
• Erwäge, sehr große Datensätze in mehrere Batches aufzuteilen, um eine bessere Handhabbarkeit zu erreichen.
• Führe einen Testlauf einer einzelnen Anfragestruktur mit der Messages API durch, um Validierungsfehler zu vermeiden.



Fehlerbehebung bei häufigen Problemen

Bei unerwartetem Verhalten:

• Überprüfe, ob die Gesamtgröße der Batch-Anfrage 256 MB nicht überschreitet. Wenn die Anfragegröße zu groß ist, erhältst du möglicherweise einen 413-Fehler request_too_large.
• Stelle sicher, dass du unterstützte Modelle für alle Anfragen im Batch 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.
• Bestätige, dass der Batch nicht abgebrochen wurde.

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



Batch-Speicherung und Datenschutz

• Workspace-Isolation: Batches sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Auf sie kann nur mit API-Keys zugegriffen werden, die diesem Workspace zugeordnet sind, oder von Nutzern mit der Berechtigung, Workspace-Batches in der Console anzuzeigen.

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



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 mit dem 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 zum Abruf der Ergebnisse.

Informationen zur ZDR-Berechtigung für alle Features findest du unter API und Datenaufbewahrung.



FAQ



Nächste Schritte