Parse Asynchronously (Parse Jobs)

Use Parse Jobs v2 to parse documents asynchronously with the Parse v2 API. Submit a document, receive a job_id immediately, then poll for the result instead of holding open a single synchronous request. 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

uses one endpoint to submit a job and two to monitor it. All calls use the same host as the synchronous 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 and ade-typescript libraries do not yet include the Parse API or . Call the endpoints directly with cURL or your HTTP client of choice.

Workflow Overview

Submit a document to POST /v2/parse/jobs.
Copy the job_id from the response.
Poll GET /v2/parse/jobs/{job_id} until status reaches a terminal state (completed, failed, or cancelled).
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: a document file upload or a document_url, with an optional model and options. Replace YOUR_API_KEY with your API key.

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:

{ "job_id": "d3kpfw9bf0ez7e501an5qqe8z" }

accepts the same options as the synchronous endpoint, including page selection, table format, and grounding detail. See 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.

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:

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.

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.
`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.
`metadata`	The result’s `metadata` block (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.
`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 for the field-by-field reference.
As a URL in output_url. If you supplied output_save_url when you created the job, saves the output to that URL, output_url contains the location, and data is null. See 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.

List Parse Jobs

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

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.

{
  "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:
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.

Rate Limits

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.

​Endpoints

​Library Support

​Workflow Overview

​Create a Parse Job

​Choose a Service Tier

​Monitor a Parse Job

​Job Statuses

​Get Job Results

​List Parse Jobs

​Save Parsed Output to a URL

​URL Requirements

​Zero Data Retention (ZDR)

​Rate Limits