> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landing.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse Asynchronously (Parse Jobs)

> Parse documents asynchronously with Parse Jobs v2: submit a job, poll for status, and retrieve results.

export const dpt3pro = 'DPT-3 Pro';

export const dpt3 = 'DPT-3';

export const parseJobs = 'Parse Jobs';

export const parseDpt3 = 'Parse';

export const ade = 'Agentic Document Extraction';

Use Parse Jobs v2 to parse documents asynchronously with the [Parse v2 API](./parse). Submit a document, receive a `job_id` immediately, then poll for the result instead of holding open a single synchronous request.

{parseJobs} runs the same parsing as the synchronous Parse API and returns the same Parse v2 response shape. Use it for workflows where you don't want to wait on a live connection, such as batch pipelines, long-running parses, and documents beyond the synchronous size limits, or when you want to submit work at a lower-cost service tier.

## Endpoints

{parseJobs} uses one endpoint to submit a job and two to monitor it. All calls use the same host as the synchronous [Parse API](./parse#call-the-parse-api), `https://api.ade.landing.ai`.

| Action             | Method and Path               |
| ------------------ | ----------------------------- |
| Create a parse job | `POST /v2/parse/jobs`         |
| Get a parse job    | `GET /v2/parse/jobs/{job_id}` |
| List parse jobs    | `GET /v2/parse/jobs`          |

## Library Support

The [ade-python](https://github.com/landing-ai/ade-python) and [ade-typescript](https://github.com/landing-ai/ade-typescript) libraries do not yet include the Parse API or {parseJobs}. Call the endpoints directly with cURL or your HTTP client of choice.

## Workflow Overview

1. Submit a document to `POST /v2/parse/jobs`.
2. Copy the `job_id` from the response.
3. Poll `GET /v2/parse/jobs/{job_id}` until `status` reaches a terminal state (`completed`, `failed`, or `cancelled`).
4. When the job completes, read the parsed output from `data`, or from `output_url` if you saved the output to a URL.

## Create a Parse Job

Submit a document the same way as the synchronous [Parse API](./parse#call-the-parse-api): a `document` file upload or a `document_url`, with an optional `model` and `options`. Replace `YOUR_API_KEY` with your [API key](./agentic-api-key).

```bash theme={null}
curl -X POST 'https://api.ade.landing.ai/v2/parse/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'model=dpt-3-pro-latest'
```

The request returns a `202` response with the `job_id`:

```json theme={null}
{ "job_id": "d3kpfw9bf0ez7e501an5qqe8z" }
```

{parseJobs} accepts the same `options` as the synchronous endpoint, including page selection, table format, and grounding detail. See [Request Options](./parse-input#request-options).

### Choose a Service Tier

Set the optional `service_tier` form field to control the job's turnaround time and credit consumption. If you omit `service_tier`, the job runs on the `standard` tier. For credit consumption by tier, see [Credit Consumption](./credit-consumption#parse-jobs).

| Tier       | Behavior                                                                                                                     |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `standard` | Consumes half the credits of the `priority` tier, with a slower turnaround. Best for cost-sensitive or non-urgent workloads. |
| `priority` | Consumes credits at the full rate, the same as synchronous parsing, with a faster turnaround. Best for time-sensitive jobs.  |

**Set the tier.**

Include the `service_tier` field in your create-job request:

```bash highlight={5} theme={null}
curl -X POST 'https://api.ade.landing.ai/v2/parse/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'service_tier=priority'
```

## Monitor a Parse Job

Poll the get-job endpoint with the `job_id` to check status and retrieve the result when the job finishes.

```bash theme={null}
curl 'https://api.ade.landing.ai/v2/parse/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response reports the job status and, once the job finishes, the result:

| Field            | Description                                                                                                                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_id`         | The unique identifier for the job.                                                                                                                                                                                                                          |
| `status`         | The current state of the job. See [Job Statuses](#job-statuses).                                                                                                                                                                                            |
| `progress`       | How far the job has progressed, from `0` to `1`.                                                                                                                                                                                                            |
| `created_at`     | When the job was created, as a Unix timestamp in seconds.                                                                                                                                                                                                   |
| `version`        | The resolved model snapshot, such as `dpt-3-pro-20260710`.                                                                                                                                                                                                  |
| `data`           | The parse result, present when `status` is `completed` and you did not save the output to a URL. Contains the full Parse v2 response (`markdown`, `metadata`, `structure`, and `grounding`). See [Parse API Response](./parse-response#the-response-shape). |
| `metadata`       | The result's [`metadata` block](./parse-response#metadata) (model version, page count, billing, and more), present when `status` is `completed`. Returned even when the output was saved to a URL.                                                          |
| `output_url`     | The location of the saved output, present only when you supplied `output_save_url`. When set, `data` is `null`. See [Save Parsed Output to a URL](#save-parsed-output-to-a-url).                                                                            |
| `failure_reason` | A description of why the job failed, present only when `status` is `failed`.                                                                                                                                                                                |

### Job Statuses

A job moves through these statuses until it reaches a terminal state.

| Status       | Meaning                                                        |
| ------------ | -------------------------------------------------------------- |
| `pending`    | The job is accepted and queued, but has not started.           |
| `processing` | The job is running.                                            |
| `completed`  | The job finished. Read the result from `data` or `output_url`. |
| `failed`     | The job did not finish. See `failure_reason` for details.      |
| `cancelled`  | The job was cancelled.                                         |

### Get Job Results

When a job reaches `completed`, the parsed output is returned in one of two ways:

* **Inline in `data`.** By default, `data` contains the full Parse v2 response. See [Parse API Response](./parse-response#the-response-shape) for the field-by-field reference.
* **As a URL in `output_url`.** If you supplied `output_save_url` when you created the job, {ade} saves the output to that URL, `output_url` contains the location, and `data` is `null`. See [Save Parsed Output to a URL](#save-parsed-output-to-a-url).

If some pages fail to parse, the completed job still returns every page and the poll request reports a `206` status. See [Troubleshoot Parsing](./parse-troubleshoot#parse-jobs).

## List Parse Jobs

To retrieve the parse jobs for your organization, call the list endpoint.

```bash theme={null}
curl 'https://api.ade.landing.ai/v2/parse/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response returns a summary for each job in `jobs`. The `has_more` field indicates whether more jobs are available beyond those returned.

```json theme={null}
{
  "jobs": [
    {
      "job_id": "d3kpfw9bf0ez7e501an5qqe8z",
      "status": "completed",
      "created_at": 1719957600,
      "received_at": 1719957600,
      "progress": 1
    }
  ],
  "org_id": "org_1a2b3c",
  "has_more": false
}
```

| Field      | Description                                                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobs`     | A summary for each job, containing `job_id`, `status`, `created_at`, `received_at`, and `progress`. A failed job also includes a `failure_reason`. |
| `org_id`   | The organization the jobs belong to.                                                                                                               |
| `has_more` | Whether more jobs are available beyond those returned.                                                                                             |

## Save Parsed Output to a URL

If you need to manage large outputs or integrate with your existing storage provider, use the `output_save_url` parameter. When you use this parameter, the output is written to the URL you specify in that parameter, instead of returning it inline in `data`.

### URL Requirements

If you specify `output_save_url`, your URL must meet these requirements:

* The URL must be a presigned URL that grants time-limited write access to a single object.
* These storage provider methods are tested:
  * [Amazon S3 presigned URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)
  * [Azure Blob Storage shared access signature (SAS)](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview)
  * [Google Cloud Storage signed URL](https://docs.cloud.google.com/storage/docs/access-control/signed-urls)
* Other providers that support presigned URLs may also work, but are not tested.
* To maintain security, do not use a publicly accessible URL or expose a storage bucket.
* The API cannot access private URLs, such as folders in Google Drive.

## Zero Data Retention (ZDR)

In Parse Jobs v1, Zero Data Retention (ZDR) required the `document_url` and `output_save_url` parameters. Parse Jobs v2 does not require these parameters; if ZDR is enabled, it applies to all Parse Jobs calls.

For the strictest control over sensitive documents, keep them out of the API request and response:

* Pass a document as a presigned URL in `document_url`.
* Write the response to a presigned URL specified in `output_save_url`. See [Save Parsed Output to a URL](#save-parsed-output-to-a-url).

## Rate Limits

{parseJobs} accepts much larger documents than the synchronous Parse v2 API: up to 6,000 pages per PDF, with a size cap of 1 GiB for PDFs and 50 MiB for images. Usage is metered against your plan's hourly limit. See [Rate Limits](./rate-limits#parse-jobs).