> ## 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: submit a job, poll for status, and retrieve results.

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

Parse Jobs runs the same parsing as the synchronous Parse API and returns the same parse 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

Parse Jobs uses one endpoint to submit a job and two to monitor it. All calls use the same host as the synchronous [Parse API](https://docs.landing.ai/dpt3/parse.md#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` |

## 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` or `failed`).
4. When the job completes, read the parsed output from `result`, 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](https://docs.landing.ai/dpt3/parse.md#call-the-parse-api): a `document` file upload or a `document_url`, with an optional `model` and `options`. Setting `service_tier` to `standard` runs the job in the lane that consumes half the credits of `priority`. Replace `YOUR_API_KEY` with your [API key](https://docs.landing.ai/dpt3/agentic-api-key.md).

```bash cURL 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=standard'
```

```python Python theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)
print(job.job_id)
```

```typescript TypeScript theme={null}
import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
  service_tier: "standard",
});
console.log(job.job_id);
```

The request returns a `202` response with the `job_id`, the job's status, and its creation time:

```json theme={null}
{
  "job_id": "parse-01k04g2b8xv9q3m5n7r2sd4tfe",
  "status": "pending",
  "created_at": "2026-07-16T18:03:12Z"
}
```

The status at creation is normally `pending`; a job that finishes very quickly can already report `completed` or `failed`. Treat the `job_id` as an opaque string; the same id is returned on every poll.

Parse Jobs accepts the same `options` as the synchronous endpoint, including page selection, table format, and grounding detail. See [Request Options](https://docs.landing.ai/dpt3/parse-input.md#request-options).

### Choose a Service Tier

Set the optional `service_tier` form field to control the job's turnaround time and credit consumption. Jobs run on the `standard` tier when you omit it.

Each tier draws from its own [rate limit](https://docs.landing.ai/dpt3/rate-limits.md): `standard` jobs are measured against your plan's hourly limit, and `priority` jobs share the synchronous Parse per-minute limit.

For a comparison of Parse and the two Parse Jobs tiers, see [Sync vs Async Processing](https://docs.landing.ai/dpt3/sync-async.md). For credit consumption by tier, see [Credit Consumption](https://docs.landing.ai/dpt3/credit-consumption.md#parse).

| Tier | Behavior |
| - | - |
| `standard` | Consumes half the credits of the `priority` tier, with a slower turnaround. The default, and the right choice for automated pipelines, background agent steps, scheduled ingestion, and the largest documents. |
| `priority` | Consumes credits at the full rate, the same as Parse, with a faster turnaround. Use it for time-sensitive jobs where someone is waiting on the result. |

**Set the tier.**

Include the `service_tier` field in your create-job request, sending `standard` or `priority`. Setting it explicitly keeps the tier visible in code you copy between projects:

```bash cURL 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=standard'
```

```python Python highlight={9} theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)
print(job.job_id)
```

```typescript TypeScript highlight={9} theme={null}
import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
  service_tier: "standard",
});
console.log(job.job_id);
```

## Monitor a Parse Job

Poll the get-job endpoint with the `job_id` to check status and retrieve the result when the job finishes. To be notified when the job finishes instead of polling, set up [webhooks](https://docs.landing.ai/dpt3/webhooks.md).

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

```python Python theme={null}
from landingai_ade import LandingAIADE

client = LandingAIADE()

# Fetch the job once. Use client.v2.parse_jobs.wait("JOB_ID") to poll until it finishes.
job = client.v2.parse_jobs.get("JOB_ID")
print(job.status)
if job.status == "completed":
    print(job.result.markdown)
```

```typescript TypeScript theme={null}
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

// Fetch the job once. Use client.v2.parseJobs.wait("JOB_ID") to poll until it finishes.
const job = await client.v2.parseJobs.get("JOB_ID");
console.log(job.status);
if (job.status === "completed") {
  console.log((job.result as LandingAIADE.V2ParseResponse).markdown);
}
```

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

| Field | Description |
| - | - |
| `job_id` | The unique identifier for the job. The same id is returned on the create response and every poll. |
| `status` | The current state of the job. See [Job Statuses](#job-statuses). |
| `created_at` | When the job was created, as an ISO-8601 timestamp. |
| `completed_at` | When the job reached a terminal state, as an ISO-8601 timestamp. Present once the job finishes. |
| `progress` | An estimate of how close the job is to completion, between `0` and `1`, updated on each poll. Present only while the job is processing, and never reaches `1`. To detect completion, check for a `status` of `completed` instead. |
| `result` | The parse result, present when `status` is `completed` and you did not save the output to a URL. Contains the full parse response (`markdown`, `metadata`, and `structure`). See [Parse API Response](https://docs.landing.ai/dpt3/parse-response.md#the-response-shape). |
| `output_url` | The location of the saved output, present when the output was delivered to your `output_save_url`. When set, the full output is delivered to the URL instead of returned in `result`. See [Save Parsed Output to a URL](#save-parsed-output-to-a-url). |
| `metadata` | The job's `metadata` block, including `billing`. Present on completed jobs that saved their output to a URL, so you can confirm the model version and charge without fetching the file. For inline results, this information is in `result.metadata` instead. See [Parse API Response](https://docs.landing.ai/dpt3/parse-response.md#metadata). |
| `error` | Present when `status` is `failed`. Contains a `code` and a `message`. |

### 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 `result` or `output_url`. |
| `failed` | The job did not finish. See the `error` field for details. |

### Get Job Results

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

* **Inline in `result`.** By default, `result` contains the full parse response. See [Parse API Response](https://docs.landing.ai/dpt3/parse-response.md#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 and delivery succeeds, Agentic Document Extraction saves the output to that URL, `output_url` contains the location, and `result` is `null`. The poll response still reports the job's `metadata`. 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](https://docs.landing.ai/dpt3/parse-troubleshoot.md#parse-jobs).

You can poll a job for up to 7 days after it completes. Without Zero Data Retention (ZDR), you can also fetch its result for up to 7 days. See [Job Result Availability](https://docs.landing.ai/dpt3/sync-async.md#job-result-availability).

## List Parse Jobs

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

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

```python Python theme={null}
from landingai_ade import LandingAIADE

client = LandingAIADE()

jobs = client.v2.parse_jobs.list()
for job in jobs:
    print(job.job_id, job.status)
```

```typescript TypeScript theme={null}
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const jobs = await client.v2.parseJobs.list();
for (const job of jobs.jobs) {
  console.log(job.job_id, job.status);
}
```

The response returns your jobs newest first, as a summary row per job. Use the optional `page` (0-indexed), `pageSize`, and `status` query parameters to page through the list or filter by job status.

```json theme={null}
{
  "jobs": [
    {
      "job_id": "parse-01k04g2b8xv9q3m5n7r2sd4tfe",
      "status": "completed",
      "created_at": "2026-07-16T18:03:12Z",
      "completed_at": "2026-07-16T18:04:37Z",
      "model_version": "dpt-3-pro-20260710",
      "failure_reason": null
    }
  ],
  "page": 0,
  "page_size": 10,
  "has_more": false
}
```

| Field | Description |
| - | - |
| `jobs` | A summary for each job, containing `job_id`, `status`, `created_at`, `completed_at`, and `model_version` (the model snapshot used). A failed job also reports a `failure_reason`. |
| `page` | The 0-indexed page number of this list response. |
| `page_size` | The number of jobs per page. |
| `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 `result`.

The delivered file contains the complete parse response: `markdown`, `metadata` (including `billing`), and `structure`. The completed poll response also carries the job's `metadata` alongside `output_url`, so billing information is available without fetching the file. Agentic Document Extraction delivers the output in one HTTP PUT request. If your endpoint returns a 5xx error or times out, the delivery is retried. If delivery fails, the job still completes and returns the output in `result` instead of `output_url`.

### 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.
* The URL must stay valid until the job completes, not just until you submit it. A URL that is already expired or expires too soon is rejected at submission with a 422 error. See [Troubleshoot Parsing](https://docs.landing.ai/dpt3/parse-troubleshoot.md#status-422-unprocessable-entity).
* An Azure SAS URL must grant write (`w`) or create (`c`) permission.
* 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)

If Zero Data Retention (ZDR) is enabled for your organization, it applies to all Parse Jobs calls. No special parameters are required. Under ZDR, results are deleted as soon as you retrieve them. See [Result Retention](https://docs.landing.ai/ade/zdr.md#result-retention).

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

Parse Jobs accepts larger files than the synchronous Parse API: a size cap of 1 GiB for PDFs and 50 MiB for images, with the same 6,000-page ceiling per PDF. Usage is metered by pages against the job's service tier: `priority` jobs draw from the same per-minute limit as synchronous Parse, and `standard` jobs are measured against your plan's hourly limit. A document with more pages than the `priority` per-minute limit cannot run on that tier; submit it on the `standard` tier. See [Rate Limits](https://docs.landing.ai/dpt3/rate-limits.md#parse-api).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.