Batch processing API
Use the batch endpoints to process up to 10 documents with the same operation and settings in one request. Each document becomes its own processing run, which you read through the runs endpoints.
Send requests to https://api.nutrient.io. Authenticate with a Data Extraction API key in the Authorization: Bearer header.
The API calls a saved preset a processor, and its ID starts with proc_.
Batches you submit through the API also appear in Studio, and batches started in Studio appear in the API. For the Studio workflow, refer to the batch processing guide.
Submit a batch
Send POST /extraction/batches as a multipart request with these fields:
| Field | Description |
|---|---|
operation | Required. One of parse, extract, classify, or split. Every document runs this operation. |
instructions | Optional. A JSON string with the settings every document uses. Without it, the operation’s defaults apply. |
files[] | Required. One document per field. Repeat the field for each document, from 1 to 10 in total. The API rejects indexed names such as files[0]. |
Set instructions in one of two ways:
- Inline settings — Send the same settings the operation’s asynchronous route accepts. For example, send
{"schema": {...}}forextract, or{"labels": [...]}forclassify. - Saved preset — Reference a processor with
{"processor": "proc_...", "version": 3}. Setversionto a version number, such as3, or to"latest". If you omitversion, the API uses"latest", which is the most recent published version. The API never runs unpublished changes, so a preset with no published version returns422. Studio differs: It runs the latest draft when no version is published. Don’t combine a processor reference with inline settings.
Batches accept uploaded files only. The API rejects a url in instructions, a single file field, and storeRun: false. For accepted formats, refer to the supported file types guide. Each document can be as large as a single run allows on your plan.
The following example extracts data from two invoices with a saved preset:
curl -i -X POST https://api.nutrient.io/extraction/batches \ -H "Authorization: Bearer your_api_key_goes_here" \ -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \ -F "operation=extract" \ -F 'instructions={"processor":"proc_01J8Z3K7QF9YB0N2M5R6X4T8AB","version":"latest"}' \ -F "files[]=@invoice-1.pdf" \ -F "files[]=@invoice-2.pdf"The API returns 202 Accepted with the batch in the running state. The Location header contains the batch’s URL, and the batch ID starts with batch_.
The API validates every document before it stores any of them. If one document or setting is invalid, the API rejects the whole batch and charges nothing.
Your workspace can run one batch at a time, shared with Studio. Submitting another batch while one is running returns 409 batch_already_running, and errorDetails.runningBatchId names the running batch.
Follow the batch
Poll GET /extraction/batches/{batchId} until status is done, error, or canceled. For an error batch, keep polling until counts.pending and counts.running are both 0, because documents already processing still finish.
Wait at least two seconds between requests. Polling and submission requests share a rate limit, so frequent polling reduces capacity for new submissions.
| Status | What it means |
|---|---|
running | At least one document is waiting or being processed. |
done | Every document finished. Individual documents can still have failed or been canceled. |
error | The batch stopped because a document couldn’t be charged. Check error for details. |
canceled | You canceled the batch before it finished. |
The response includes counts with the number of documents in each state: total, pending, running, succeeded, failed, and canceled.
The documents array lists one entry for each document, in the order you sent them. Each entry contains these fields:
runId— The document’s processing run.fileName— The name of the uploaded file.status— The run’s status, such asdone,error, orcanceled.error— The run’s error details when it failed, ornull.resultAvailable—falseonce the run was deleted, expired, or lost its stored result.
The following response shows the batch from the submission example while its second document is still processing:
{ "id": "batch_01J8Z3K7QF9YB0N2M5R6X4T8AB", "status": "running", "operation": "extract", "processor": { "id": "proc_01J8Z3K7QF9YB0N2M5R6X4T8AB", "name": "Invoices", "version": 3, "deleted": false }, "error": null, "createdAt": "2026-11-09T10:15:00Z", "startedAt": "2026-11-09T10:15:00Z", "finishedAt": null, "counts": { "total": 2, "pending": 0, "running": 1, "succeeded": 1, "failed": 0, "canceled": 0 }, "documents": [ { "runId": "7KQ1798ESSE966BQNKQJXMQZHF", "fileName": "invoice-1.pdf", "status": "done", "error": null, "resultAvailable": true }, { "runId": "7KQ1798ESSE966BQNKQJXMQZHG", "fileName": "invoice-2.pdf", "status": "running", "error": null, "resultAvailable": true } ]}One failed document doesn’t stop the others. Check each document’s status rather than relying on the batch status alone.
Read each result
Read each document’s result through its run. Use GET /extraction/runs/{runId} for the run, and download its result asset when the run’s status is done. For details, refer to the run asynchronously guide.
The API doesn’t provide a single result for the whole batch.
Cancel a batch
Send POST /extraction/batches/{batchId}/cancel to stop a running batch. The API cancels documents that haven’t finished, including documents being processed. It discards their results and doesn’t charge for them. Documents that already finished keep their results.
Canceling a batch that’s already canceled returns 200 with the batch again, so retrying a cancellation is safe. A batch with status error stays error, and its documents that are still running are canceled. Canceling a batch with status done returns 409 batch_not_cancelable.
List batches
Send GET /extraction/batches to list your workspace’s batches, newest first. The list includes batches started in Studio.
Use page_size to set the number of batches per page. It defaults to 50, and the API caps it at 100. When pagination.next_cursor isn’t null, pass it as cursor to read the next page.
Retry safely with an idempotency key
Include an Idempotency-Key header to retry a submission safely. The key contains 1 to 255 printable characters.
Retrying with the same key and the same request returns 202 with the existing batch in its current state and an Idempotency-Replayed: true header. It doesn’t start another batch. The same request means the same settings, files in the same order, engine version, and processor version. Reusing the key for a different request returns 409 idempotency_key_reused.
The API resolves "version": "latest" when you submit. If you publish a newer processor version before retrying, the retry counts as a different request and returns 409.
The key’s scope covers your workspace, not a single operation, and Studio batches share it. A batch keeps its key after it finishes, fails, or is canceled, until the batch is deleted in Studio. To submit the same documents again, use a new key.
Credits
Each document uses credits like any other run of the same operation. The API doesn’t return a cost estimate.
The API checks your credits when you submit a batch. Insufficient credits return 402, and the API doesn’t queue anything.
If a document can’t be charged while the batch runs, the batch stops with status error. Documents still waiting are canceled, and documents already processing finish.
Errors
Batch requests return the following errors, in addition to the validation errors of the selected operation:
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request is malformed. errorDetails.failingPaths names each invalid field. |
| 400 | idempotency_key_invalid | The Idempotency-Key doesn’t contain 1 to 255 printable characters. |
| 402 | — | Insufficient credits or run storage. The API didn’t queue the batch. |
| 404 | batch_not_found | The batch doesn’t exist, it belongs to another workspace, or your workspace can’t use batches. |
| 409 | batch_already_running | Another batch is running in your workspace. errorDetails.runningBatchId names it. |
| 409 | batch_not_cancelable | The batch you tried to cancel has already finished. |
| 409 | idempotency_key_reused | Another request already uses this Idempotency-Key. |
| 413 | batch_file_too_large | A document exceeds the size limit for your plan. errorDetails names the file and the limit. |
| 413 | batch_request_too_large | The request is too large, or operation and instructions together exceed 1 MB. |
| 422 | batch_empty | The request contains no documents. |
| 422 | batch_too_large | The request contains more than 10 documents. |
| 429 | — | You exceeded the rate limit for your plan. |
| 503 | enqueue_failed | The API couldn’t queue the batch. Submit the request again. |
A processor reference that doesn’t resolve returns 422 in the operation’s own error format. Refer to the error handling guide for response formats.
Next steps
Use these references for run management and response details:
- Refer to the processing runs guide for reading, listing, and deleting runs, and for retention.
- Refer to the API reference for the full request and batch schemas.