---
title: "Batch processing API"
canonical_url: "https://www.nutrient.io/guides/dws-data-extraction/batches/api/"
md_url: "https://www.nutrient.io/guides/dws-data-extraction/batches/api.md"
last_updated: "2026-11-12T00:00:00.000Z"
description: "Submit up to 10 documents for parse, extract, classify, or split in one request. Follow the batch, read each result, cancel it, and list batches."
---

# 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](https://www.nutrient.io/guides/dws-data-extraction/batches.md) 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": {...}}` 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](https://www.nutrient.io/guides/dws-data-extraction/file-types.md) 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:

```shell

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 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:

```json

{
  "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](https://www.nutrient.io/guides/dws-data-extraction/runs/async.md) 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](https://www.nutrient.io/guides/dws-data-extraction/errors.md) guide for response formats.

## Next steps

Use these references for run management and response details:

- Refer to the [processing runs](https://www.nutrient.io/guides/dws-data-extraction/runs.md) guide for reading, listing, and deleting runs, and for retention.

- Refer to the [API reference](https://www.nutrient.io/api/reference/data-extraction/public/) for the full request and batch schemas.
---

## Related pages

- [Batch processing](/guides/dws-data-extraction/batches.md)

