Batches

Ein Batch ist eine benannte Gruppe von einem oder mehreren Dokumenten, die Sie gemeinsam verarbeiten, abfragen und Ergebnisse abrufen. Sie erstellen keinen Batch explizit – er wird implizit beim ersten Hochladen eines Dokuments mit diesem batch_name erstellt (siehe Dokument hochladen).

Verarbeitung eines Batches starten

Startet die Extraktion für jedes berechtigte Dokument im Batch (alles, was nicht bereits processing oder succeeded ist). Dieser Endpunkt verbraucht tatsächlich Guthaben – eines pro eingereihtem Dokument.

POST /api/v1/batches/{batch_name}/process

Parameter

Name	Ort	Typ	Beschreibung
`batch_name`	Pfad	string	Der zu verarbeitende Batch.
`template_id`	Body (JSON)	integer, optional	Eine gespeicherte Vorlage, die angewendet werden soll. Hat Vorrang vor `fields`, falls beide angegeben sind.
`fields`	Body (JSON)	array, optional	Ad-hoc-Feldliste nur für diesen Durchlauf – `[{"name": "...", "format_requirement": "..."}]` oder ein einfaches Array von Namensstrings. Wird ignoriert, wenn `template_id` angegeben ist. Lassen Sie beide weg, damit das Modell Spalten selbst ableiten kann.
`quality`	Body (JSON)	string, optional	`"fast"` oder `"high"`. Weglassen, um auf die `thinking_type`-Einstellung Ihres Kontos zurückzufallen – siehe Kontoeinstellungen & API-Verhalten.
`webhook_url`	Body (JSON)	string, optional	Registriert (oder aktualisiert) den Abschluss-Callback dieses Batches im selben Aufruf – gleichbedeutend mit dem zusätzlichen Aufruf von Batch-Webhook registrieren. Muss `http://` oder `https://` sein.
`Idempotency-Key`	Header, optional	string	Stark empfohlen – dieser Endpunkt verbraucht Guthaben. Siehe Idempotenz.

quality ist die einzige Kontoeinstellung, die die API pro Aufruf überschreiben lässt – jede andere Einstellung auf Kontoebene (bbox-Auto-Annotation, Aufbewahrungsrichtlinie) wird von Ihrem Konto gelesen und kann nicht pro Anfrage überschrieben werden. Siehe Kontoeinstellungen & API-Verhalten für das vollständige Bild, einschließlich warum auto_annotate_bbox dazu führen kann, dass Ihnen dieser Aufruf auch die bbox-Annotation in Rechnung stellt, obwohl Sie diesen Endpunkt nie aufgerufen haben.

Das webhook_registered in der Antwort bezieht sich nur auf diesen spezifischen Aufruf – es ist true genau dann, wenn diese Anfrage webhook_url enthielt, nicht ob der Batch überhaupt einen Webhook hat. Ein Batch, dessen Webhook zuvor über Batch-Webhook registrieren eingerichtet wurde (und hier nicht wiederholt wird), löst seinen Callback bei Abschluss korrekt aus, aber dieses Feld gibt für diesen Aufruf dennoch false zurück – es prüft nicht, ob bereits ein BatchWebhook existiert. Behandeln Sie ein false hier nicht als „für diesen Batch wird kein Webhook ausgelöst.“

Wenn Sie diesen Endpunkt erneut für einen Batch aufrufen, den Sie bereits verarbeitet haben und über den Sie benachrichtigt wurden – nachdem Sie weitere Dokumente hochgeladen haben – wird der Webhook dieses Batches automatisch wieder aktiviert, falls er bereits ausgelöst wurde, sodass auch der Abschluss der neuen Welle benachrichtigt. Es ist kein zusätzlicher Aufruf erforderlich, um dies zu erreichen; siehe den Abschnitt „Batch erneut verarbeiten“ im Webhooks-Leitfaden für die genaue Semantik (einschließlich was passiert, wenn sich zwei Wellen überschneiden).

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required – siehe Fehlerbehandlung.
batch_not_found – unter diesem batch_name existieren in Ihrem Konto keine Dokumente.
invalid_parameter – ungültiger Wert für quality/webhook_url/template_id, oder es befinden sich derzeit keine Dokumente im Batch, die für die Verarbeitung in Frage kommen (alle bereits abgeschlossen/in Verarbeitung, oder der Batch ist leer).
template_not_found
insufficient_credits – nicht genügend verfügbare Credits, um die in die Warteschlange gestellten Dokumente abzudecken.

Batches auflisten

Gibt eine paginierte, filterbare Zusammenfassungsliste Ihrer Batches zurück – das Äquivalent zu „Files Filter“ für API-Nutzer. Diese liefert nur Zusammenfassungen (document_count, aggregierter status); verwenden Sie Batch-Ergebnisse abrufen für die vollständigen, dokumentbezogenen Daten eines bestimmten Batches.

GET /api/v1/batches

Parameter

Name	Ort	Typ	Beschreibung
`source`	query, optional	string	Einer von `direct`, `collect`, `email_inbox`, `api` (hochgeladen via `POST /documents`, abweichend von `direct`, der Haupt-Web-App) oder `share` (ein Alias, der sowohl `collect` als auch `email_inbox` abdeckt). Für alle Quellen weglassen.
`q`	query, optional	string	Groß-/Kleinschreibung-unabhängige Teilzeichenfolgensuche in Dateinamen innerhalb des Batches.
`date_from`	query, optional	string (`YYYY-MM-DD`)	Inklusive untere Grenze für den Upload-Zeitpunkt.
`date_to`	query, optional	string (`YYYY-MM-DD`)	Inklusive obere Grenze für den Upload-Zeitpunkt (Tagesende).
`status`	query, optional	string	Kommagetrennte Liste öffentlicher Status (`queued,processing,succeeded,failed,canceled`) zum Filtern.
`template_id`	query, optional	integer	Nur Batches, die diese Vorlage verwendet haben.
`mode`	query, optional	string	Einzig akzeptierter Wert ist derzeit `"table"` (der einzige Modus, den v1 derzeit unterstützt). Für zukünftige Extraktionsmodi reserviert.
`limit`	query, optional	integer	1–100. Standard 20.
`page_token`	query, optional	string	Undurchsichtiger Cursor aus dem `next_page_token` einer vorherigen Antwort. Siehe Paginierung.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
invalid_parameter — ungültiger mode, limit, status oder page_token.

Batch-Status abrufen

Leichtgewichtiger aggregierter Status für einen Batch – zählt pro öffentlichem Status plus einem all_done-Flag. Nützlich für eine günstige Polling-Schleife, die noch nicht die vollständigen Ergebnisse benötigt.

GET /api/v1/batches/{batch_name}

Parameter

Name	Ort	Typ	Beschreibung
`batch_name`	Pfad	string	Der zu prüfende Batch.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
batch_not_found

Batch-Ergebnisse abrufen

Die primäre Methode zum Abrufen extrahierter Daten. Jedes Dokument im Batch wird mit seinen umgeformten line_items zurückgegeben – einem Array von {field_name: value}-Objekten, eines pro extrahierter Zeile. Feldwerte sind standardmäßig einfache Skalare (ein String, eine Zahl usw.).

GET /api/v1/batches/{batch_name}/results

Parameter

Name	Ort	Typ	Beschreibung
`batch_name`	Pfad	string	Der Batch, für den Ergebnisse abgerufen werden sollen.
`include`	Abfrage, optional	string	`"bbox"` – wenn gesetzt, wird jeder Feldwert zu `{"value": ..., "bbox": {...}\|null}` anstelle eines einfachen Skalars, und jedes Dokument erhält ein `bbox_status`-Feld. Siehe unten – dies löst niemals einen neuen bbox-Job aus, sondern gibt nur zurück, was bereits berechnet wurde.

?include=bbox liest nur nachträglich ausgefüllte Ergebnisse – es ruft nicht bbox-Annotation auslösen für Sie auf. Wenn bbox für ein Dokument nie ausgelöst wurde (manuell oder über die auto_annotate_bbox-Einstellung Ihres Kontos), werden die Felder dieses Dokuments einfach mit "bbox": null zurückgegeben.

Reine Positionsfelder haben eine dritte, eigenständige Form. Einige Vorlagenfelder fordern das Modell auf, etwas zu lokalisieren statt Text zu transkribieren (z. B. „das Porträtfoto lokalisieren"). Bei diesen Feldern ist der gesamte Wert eine Position – daher erhalten Sie statt eines Skalars oder des {"value","bbox"}-Paares {"type": "image_region", "bbox": {...}, "image_url": "..."}, unabhängig davon, ob ?include=bbox gesetzt war – die Box ist hier keine optionale Metadaten, sondern der einzige Inhalt des Feldes. image_url verweist auf ein abrufbereites, zugeschnittenes JPEG (siehe Dokumentbild abrufen), sodass Sie das Original nicht selbst aus vier Zahlen zuschneiden müssen.

Jedes bbox-Objekt – in beiden Formen – verwendet "unit": "normalized": Koordinaten sind Fließkommazahlen von 0 bis 1 relativ zur Seitenbreite/-höhe, nicht Pixel und keine 0–1000-Skala. Beachten Sie die Bounding-Boxes-Anleitung zum Genauigkeitshinweis – diese Koordinaten stammen direkt aus dem Modell ohne pixelgenaue Überprüfung, behandeln Sie sie daher bei dichten oder komplexen Dokumenten als „ungefähr" statt exakt.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required – siehe Fehlerbehandlung.
batch_not_found

Batch exportieren

Ein praktischer Download – results oben ist das kanonische, strukturierte Format, um das diese API herum aufgebaut ist; dieser Endpunkt dient dazu, dieselben Daten ohne eigenes Umformungs-Script in eine Tabelle zu laden. Nur xlsx – v1 unterstützt ausschließlich den Tabellenmodus (Extract), und der Word-Export (docx) in der Haupt-App ist ausschließlich die native Ausgabe des page_word-Modus (ein völlig anderer Prompt und eine andere Ergebnisstruktur), die v1 nicht bereitstellt. Es gibt hier keine Option „Tabellendaten als Word-Dokument".

GET /api/v1/batches/{batch_name}/export

Parameter

Name	Ort	Typ	Beschreibung
`batch_name`	Pfad	string	Der zu exportierende Batch.
`format`	Abfrage, optional	string	Nur `xlsx` (Standard) wird akzeptiert.

Die Antwort ist ein Datei-Download (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), kein JSON – es gibt kein JSON-Antwortbeispiel für diesen Endpunkt.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
batch_not_found
invalid_parameter (param: "format") — alles außer xlsx.

Batch löschen

Löscht dauerhaft jedes Dokument im Batch. Jedes noch queued Dokument wird vor dem Löschen rückerstattet. Dies entfernt auch die Webhook-Registrierung des Batches (falls vorhanden) und alle mit seinen Dokumenten verbundenen bbox-Annotationsaufträge.

DELETE /api/v1/batches/{batch_name}

Parameter

Name	Ort	Typ	Beschreibung
`batch_name`	Pfad	string	Der zu löschende Batch.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
batch_not_found — anders als bei manchen anderen Ressourcen führt das Löschen eines batch_name, der Ihnen nicht gehört (oder nicht existiert), hier zu einem 404, nicht zu einem stillen No-op.