This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/dws-data-extraction/batches/api.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. 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:

FieldDescription
operationRequired. One of parse, extract, classify, or split. Every document runs this operation.
instructionsOptional. 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": {...}} for extract, or {"labels": [...]} for classify.
  • Saved preset — Reference a processor with {"processor": "proc_...", "version": 3}. Set version to a version number, such as 3, or to "latest". If you omit version, the API uses "latest", which is the most recent published version. The API never runs unpublished changes, so a preset with no published version returns 422. 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:

Terminal window
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.

StatusWhat it means
runningAt least one document is waiting or being processed.
doneEvery document finished. Individual documents can still have failed or been canceled.
errorThe batch stopped because a document couldn’t be charged. Check error for details.
canceledYou 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 as done, error, or canceled.
  • error — The run’s error details when it failed, or null.
  • resultAvailable — false once 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:

StatusCodeMeaning
400invalid_requestThe request is malformed. errorDetails.failingPaths names each invalid field.
400idempotency_key_invalidThe Idempotency-Key doesn’t contain 1 to 255 printable characters.
402—Insufficient credits or run storage. The API didn’t queue the batch.
404batch_not_foundThe batch doesn’t exist, it belongs to another workspace, or your workspace can’t use batches.
409batch_already_runningAnother batch is running in your workspace. errorDetails.runningBatchId names it.
409batch_not_cancelableThe batch you tried to cancel has already finished.
409idempotency_key_reusedAnother request already uses this Idempotency-Key.
413batch_file_too_largeA document exceeds the size limit for your plan. errorDetails names the file and the limit.
413batch_request_too_largeThe request is too large, or operation and instructions together exceed 1 MB.
422batch_emptyThe request contains no documents.
422batch_too_largeThe request contains more than 10 documents.
429—You exceeded the rate limit for your plan.
503enqueue_failedThe 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.