> ## 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` |
## 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](./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 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'
```
```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",
)
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",
});
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.
{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.
Each tier draws from its own [rate limit](./rate-limits): `priority` jobs share the synchronous Parse per-minute limit, and `standard` jobs are measured against your plan's hourly limit.
If you omit `service_tier`, the job runs on the `standard` tier.
For a comparison of Parse and the two Parse Jobs tiers, see [Sync vs Async Processing](./sync-async). For credit consumption by tier, see [Credit Consumption](./credit-consumption#parse).
| 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 Parse, with a faster turnaround. Best for time-sensitive jobs. |
**Set the tier.**
Include the `service_tier` field in your create-job request:
```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=priority'
```
```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="priority",
)
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: "priority",
});
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.
```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, { type V2ParseResponse } 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 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 v2 response (`markdown`, `metadata`, and `structure`). See [Parse API Response](./parse-response#the-response-shape). |
| `output_url` | The location of the saved output, present only when you supplied `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](./parse-response#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 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 `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](./parse-troubleshoot#parse-jobs).
## 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), `page_size`, 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 v2 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.
### 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 larger files than the synchronous Parse v2 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](./rate-limits#parse-v2-api).