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 — 1 credit per document queued if your account is on the Standard Model Tier, the default every account starts on. If your account has been assigned Advanced or Premium instead, each document costs 3 or 6 credits respectively — the tier changes which model runs the extraction, not what fields come back or how the response is shaped, so nothing else about this endpoint's contract changes. There's no tier parameter on this request: Model Tier is an account-level setting the ImageToTable.ai team assigns, not something a caller picks per batch. The tier in effect at the moment this endpoint is called is the one that's charged, and it stays locked to whatever documents it queues here even if the account's tier changes before they finish — a batch split across multiple process calls can have different documents billed at different tiers if the account's tier changed in between. See Account Settings & API Behavior for the full settings table, and Account usage for how a non-Standard deduction is labeled in your credit ledger.

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. One behavioral difference worth knowing: if the batch's template has Multi-Page Merge configured, this endpoint always applies it — unlike results, there's no opt-out query param here, since a spreadsheet download has no existing-integration compatibility concern to preserve.

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.