> For the complete documentation index, see [/llms.txt](/llms.txt).

> Source: /api/parse/document-parsing/async

# Asynchronous API

## Create Request

Submit an inference request for a supported document with up to 2,000 pages. Upon receiving the request, the API immediately returns a Request ID. The input file is divided into batches of 10 pages each, and inference is performed on each batch.

OpenAPI spec: `./openapi/openapi-document-digitization-dp-async.yaml`

- `POST /document-digitization/async`

<br />

### Response

<table><tbody><tr><td><strong>request\_id</strong> string<br />
The unique identifier for the async request. Use this ID to retrieve the inference results.</td></tr></tbody></table>

---

## Retrieve Results

Retrieve inference results by request ID and check the status of each batch in real-time.

**How to get your parsed results:**

1. Poll this endpoint until the top-level `status` is `completed` (or track each `batches[].status` individually).
2. For each completed batch, download its result from `batches[].download_url`.
3. Each download is a JSON object in the **same format as the [synchronous Document Parse response](/api/parse/document-parsing)** — `elements`, `content` (`html`/`markdown`/`text`), `coordinates`, `usage`, and so on — covering the pages from that batch's `start_page` to `end_page`.
4. Concatenate the batches in `id` order to reconstruct the full document.

Each `download_url` is a pre-signed link valid for 15 minutes; re-fetch this endpoint to obtain fresh URLs. Results remain available for 30 days from the time of the request.

OpenAPI spec: `./openapi/openapi-document-digitization-dp-async.yaml`

- `GET /document-digitization/requests/{request_id}`

<br />

### Response

<table><tbody><tr><td><strong>id</strong> string<br />
The unique identifier for the request.</td></tr><tr><td><strong>status</strong> string<br />
Current status of the request. Possible values are `submitted`, `started`, `completed`, `failed`, `deleted`.</td></tr><tr><td><strong>model</strong> string<br />
The model alias used for the request.</td></tr><tr><td><strong>failure\_message</strong> string<br />
Error message if the request failed. Empty string if successful.</td></tr><tr><td><strong>total\_pages</strong> integer<br />
Total number of pages in the input document.</td></tr><tr><td><strong>completed\_pages</strong> integer<br />
Number of pages that have been processed.</td></tr><tr><td><strong>batches</strong> array<br />
Array of batch processing information. Each batch contains up to 10 pages.</td></tr><tr><td><strong>batches\[].id</strong> integer<br />
Batch identifier (1-indexed).</td></tr><tr><td><strong>batches\[].model</strong> string<br />
The specific model version used for this batch.</td></tr><tr><td><strong>batches\[].status</strong> string<br />
Status of this batch. Possible values are `scheduled`, `started`, `completed`, `failed`, `retrying`.</td></tr><tr><td><strong>batches\[].failure\_message</strong> string<br />
Error message if the batch failed. Empty string if successful.</td></tr><tr><td><strong>batches\[].download\_url</strong> string<br />
Pre-signed URL to download this batch's result. The downloaded file is a JSON object in the same format as the <a href="/api/parse/document-parsing">synchronous Document Parse response</a> (<code>elements</code>, <code>content</code>, <code>coordinates</code>, <code>usage</code>, …), covering pages <code>start\_page</code> through <code>end\_page</code>. Valid for 15 minutes after issuance; re-fetch this endpoint to obtain a new URL.</td></tr><tr><td><strong>batches\[].start\_page</strong> integer<br />
First page number in this batch (1-indexed).</td></tr><tr><td><strong>batches\[].end\_page</strong> integer<br />
Last page number in this batch.</td></tr><tr><td><strong>batches\[].requested\_at</strong> string<br />
Timestamp when the batch was requested (UTC, ISO 8601 format).</td></tr><tr><td><strong>batches\[].updated\_at</strong> string<br />
Timestamp when the batch status was last updated (UTC, ISO 8601 format).</td></tr><tr><td><strong>requested\_at</strong> string<br />
Timestamp when the request was submitted (UTC, ISO 8601 format).</td></tr><tr><td><strong>completed\_at</strong> string<br />
Timestamp when all batches completed processing (UTC, ISO 8601 format).</td></tr></tbody></table>

---

## List Requests

Retrieve a list of all your document parsing async requests with their status and timestamps.

OpenAPI spec: `./openapi/openapi-document-digitization-dp-async.yaml`

- `GET /document-digitization/requests`

<br />

### Response

<table><tbody><tr><td><strong>requests</strong> array<br />
Array of request summary objects.</td></tr><tr><td><strong>requests\[].id</strong> string<br />
The unique identifier for the request.</td></tr><tr><td><strong>requests\[].status</strong> string<br />
Current status of the request. Possible values are `submitted`, `started`, `completed`, `failed`, `deleted`.</td></tr><tr><td><strong>requests\[].model</strong> string<br />
The model alias used for the request.</td></tr><tr><td><strong>requests\[].requested\_at</strong> string<br />
Timestamp when the request was submitted (UTC, ISO 8601 format).</td></tr><tr><td><strong>requests\[].completed\_at</strong> string<br />
Timestamp when the request completed (UTC, ISO 8601 format).</td></tr></tbody></table>

---

## Delete Inference Results

Permanently delete a request's inference results. Any `download_url` issued earlier stops working.

Only finished requests can be deleted. A request that is still processing is rejected with `request_in_progress` — retry once it completes.

Deleting an already deleted request succeeds again, so the call is safe to retry.

### Delete a single request

OpenAPI spec: `./openapi/openapi-document-digitization-dp-async.yaml`

- `DELETE /document-digitization/requests/{request_id}`

<br />

#### Response

<table><tbody><tr><td><strong>id</strong> string<br />
The request whose inference results were deleted.</td></tr><tr><td><strong>deleted</strong> boolean<br />
Always `true`. Deleting an already deleted request succeeds again.</td></tr></tbody></table>

### Delete multiple requests

Send up to 100 request IDs in one call. Duplicate IDs are collapsed, so the `results` array can be shorter than the list you sent.

OpenAPI spec: `./openapi/openapi-document-digitization-dp-async.yaml`

- `POST /document-digitization/requests/delete`

<br />

#### Response

<table><tbody><tr><td><strong>results</strong> array<br />
One entry per unique request ID, in the order they were supplied.</td></tr><tr><td><strong>results\[].request\_id</strong> string<br />
The request ID this outcome refers to.</td></tr><tr><td><strong>results\[].deleted</strong> boolean<br />
Whether this request's inference results were deleted.</td></tr><tr><td><strong>results\[].error</strong> object<br />
Present only when `deleted` is `false`. Contains `code`, `message` and `type`.</td></tr></tbody></table>

> Deletion cannot be undone. Download the results you need before deleting.

> The bulk endpoint returns `200` whenever the call itself is valid — even if every request ID failed. Check `results[].deleted` rather than relying on the HTTP status alone. Problems with the call itself, such as sending more than 100 IDs or an empty list, return `4xx`.

---

## Handling Errors

In Document Parse Async APIs, errors can occur in three different scenarios:

### Request errors

This error occurs when the input document cannot be handled by the API or if there's an error during processing, such as image conversion or page split. In case of a request failure, instead of returning a request ID, the API returns an object with error code and message.

| Error message                                             | HTTP status code |
| --------------------------------------------------------- | ---------------- |
| invalid model name                                        | 400              |
| no document in the request                                | 400              |
| uploaded document is too large. max allowed size is 500MB | 413              |
| unsupported document format                               | 415              |

### Batch inference errors

Due to the engine dividing the input document into batches of 10 pages each, each batch may have a different status for model inference. As the input file has already been validated before inference, batch inference errors are most likely caused by internal server errors. When this occurs, the API response for retrieving the result will show a `failed` status in the `batches` field with a `failure_message`.

### Failures to retrieve the request result

In the Document Parse Async API, inference results are stored for 30 days, but the `download_url` is valid for only 15 minutes after it is issued. Each call to `requests/{request_id}` generates a new pre-signed URL. If you try to access an expired URL, a 403 error may occur. To get the result again, re-fetch it using the same `request_id` — this will issue a fresh `download_url` without additional credits.