Batches

A Batch is a named group of one or more Documents that you process, poll, and fetch results for together. You don't create a batch explicitly — it's created implicitly the first time you upload a document with that batch_name (see Upload a document).

Start processing a batch

Starts extraction on every eligible document currently in the batch (anything not already processing or succeeded). This is the endpoint that actually spends credits — one per document queued.

Parameters

quality is the one account setting the API lets you override per call — every other account-level preference (bbox auto-annotation, retention policy) is read from your account and can't be overridden per request. See Account Settings & API Behavior for the full picture, including why auto_annotate_bbox can mean this call ends up billing you for bbox annotation too, even though you never called that endpoint.

The response's webhook_registered reflects only this specific call — it's true iff this request included webhook_url, not whether the batch has a webhook at all. A batch whose webhook was set up earlier via Register a batch webhook (and not repeated here) will correctly fire its callback on completion, but this field still comes back false for that call — it does not look up whether a BatchWebhook already exists. Don't treat a false here as "no webhook will fire for this batch."

Calling this endpoint again on a batch you've already processed and been notified about — after uploading more documents into it — automatically re-arms that batch's webhook if it had already fired, so the new wave's completion notifies too. No extra call is needed to make this happen; see the Webhooks guide's "Reprocessing a batch" section for the exact semantics (including what happens if two waves overlap).

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• batch_not_found — no documents exist under this batch_name on your account.
• invalid_parameter — bad quality/webhook_url/template_id value, or no documents in the batch are currently eligible for processing (all already completed/processing, or the batch is empty).
• template_not_found
• insufficient_credits — not enough available credits to cover the documents being queued.

List batches

Returns a paginated, filterable summary list of your batches — the "Files Filter" equivalent for API consumers. This returns summaries only (document_count, aggregate status); use Get batch results for the full per-document data of a specific batch.

Parameters

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• invalid_parameter — bad mode, limit, status, or page_token.

Get batch status

Lightweight aggregate status for one batch — counts per public status plus an all_done flag, useful for a cheap polling loop that doesn't need the full result payload yet.

Parameters

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• batch_not_found

Get batch results

The primary way to retrieve extracted data. Every document in the batch is returned with its reshaped line_items — an array of {field_name: value} objects, one per extracted row. Field-level values are bare scalars by default (a string, number, etc.).

Parameters

?include=bbox reads back-filled results only — it does not call Trigger bbox annotation for you. If bbox was never triggered for a document (manually, or via your account's auto_annotate_bbox setting), that document's fields simply come back with "bbox": null.

Pure-location fields are a third, distinct shape. Some template fields ask the model to locate something rather than transcribe text (e.g. "locate the portrait photo"). For those fields, the entire value is a location — so instead of a scalar or the {"value","bbox"} pair above, you get {"type": "image_region", "bbox": {...}, "image_url": "..."}, regardless of whether ?include=bbox was set — the box isn't optional metadata here, it's the field's only content. image_url points at a ready-to-fetch cropped JPEG (see Get a document's image) so you don't have to crop the original yourself from four numbers.

Every bbox object — in either shape — uses "unit": "normalized": coordinates are floats from 0 to 1 relative to the page's width/height, not pixels and not a 0–1000 scale. See the Bounding Boxes guide for the accuracy caveat — these coordinates come straight from the model with no pixel-level verification pass, so treat them as "close" rather than exact on dense or complex documents.

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• batch_not_found

Export a batch

A convenience download — results above is the canonical, structured format this API is built around; this endpoint exists for pulling the same data into a spreadsheet without writing any reshaping code yourself. xlsx only — v1 only supports table (extract) mode, and Word (docx) export on the main app is exclusively the page_word mode's native output (a different prompt and result shape entirely), which v1 doesn't expose. There's no "table data as a Word doc" option here.

Parameters

The response is a file download (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), not JSON — there's no response JSON example for this endpoint.

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• batch_not_found
• invalid_parameter (param: "format") — anything other than xlsx.

Delete a batch

Permanently deletes every document in the batch. Any document still queued is refunded before deletion. This also removes the batch's webhook registration (if any) and any bbox-annotation jobs tied to its documents.

Parameters

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• batch_not_found — unlike some other resources, deleting a batch_name you don't own (or that doesn't exist) is a 404 here, not a silent no-op.