| Option | What it does |
| ------------------------ | ------------------------------------------------------- |
| Copy page | Copies the page as Markdown |
| View as Markdown | Opens the page in Markdown format |
| Open in ChatGPT | Creates a ChatGPT conversation with the page as context |
| Open in Claude | Creates a Claude conversation with the page as context |
| Connect to Cursor | Installs the ADE docs MCP server in Cursor |
| Connect to VS Code | Installs the ADE docs MCP server in VS Code |
| Copy MCP server URL | Copies `https://docs.landing.ai/mcp` to your clipboard |
| Copy MCP install command | Copies the MCP server install command to your clipboard |
## Access Documentation Pages as llms.txt
Access an index of all Agentic Document Extraction documentation pages at [llms.txt](https://docs.landing.ai/llms.txt). For a combined file of all documentation content, use [llms-full.txt](https://docs.landing.ai/llms-full.txt).
These files follow the [llms.txt standard](https://llmstxt.org) for AI tool consumption.
## Access Documentation as Markdown
View any page as plain Markdown by adding `.md` to the page URL.
# API Key
Source: https://docs.landing.ai/dpt3/agentic-api-key
Create an API key and set it for the client libraries or direct API calls.
Calling the Agentic Document Extraction API requires an API key.
* [Get your API key](#get-your-api-key)
* [Set your API key when using a library](#set-your-api-key-when-using-a-library)
* [Set your API key when calling the API directly](#set-your-api-key-when-calling-the-api-directly)
## Get Your API Key
` elements and bracketed labels such as `[SIGNED]`) instead of `<:: ... ::>` tags, and remove any code that parses `` anchors out of the Markdown.
* If your workflow chained Parse with the Extract Gen1 API, move the extraction step to the [Extract Gen2](./extract) API. If it used Section, keep that workflow on the Parse Gen1 API.
# Python Library
Source: https://docs.landing.ai/dpt3/ade-python
Process documents using the ADE Python library.
The [ade-python](https://github.com/landing-ai/ade-python) library wraps the Agentic Document Extraction APIs so you can parse and extract documents from Python. The library is published as the `landingai-ade` package and generated from the API specification.
The Gen2 APIs live under the `client.v2` sub-client. It exposes both processing modes: async jobs through `client.v2.parse_jobs` and `client.v2.extract_jobs`, and synchronous calls through `client.v2.parse` and `client.v2.extract`. Jobs accept larger documents, default to the lower-consumption `standard` service tier, and suit automated pipelines and background work. See [Sync vs Async Processing](./sync-async).
## Install the Library
Requires Python 3.9 or later.
```bash theme={null}
pip install landingai-ade
```
## Set Your API Key
The library reads your API key from the `VISION_AGENT_API_KEY` environment variable. [Generate an API key](./agentic-api-key) first, then set it using any of the methods below. Do not hard-code your API key in source files.
### Method 1: Set the API Key as an Environment Variable
1. Set the environment variable. To persist the key across sessions on macOS or Linux, add the `export` command to your shell profile (`.zshrc` or `.bashrc`), then run `source ~/.zshrc`.
```bash macOS/Linux theme={null}
export VISION_AGENT_API_KEY=""
```
```cmd Windows (Command Prompt) theme={null}
set "VISION_AGENT_API_KEY="
```
```powershell Windows (PowerShell) theme={null}
$env:VISION_AGENT_API_KEY=""
```
2. Initialize the client. It reads the `VISION_AGENT_API_KEY` environment variable automatically:
```python theme={null}
from landingai_ade import LandingAIADE
client = LandingAIADE()
```
### Method 2: Store the API Key in a .env File
Store your API key in a `.env` file. The library reads the key from the environment; it does not load `.env` files on its own, so use `python-dotenv` to load the file.
1. Install the `python-dotenv` package:
```bash theme={null}
pip install python-dotenv
```
2. Create a `.env` file in your project root and add your API key:
```bash theme={null}
VISION_AGENT_API_KEY=
```
3. Load the `.env` file before you initialize the client:
```python theme={null}
from dotenv import load_dotenv
from landingai_ade import LandingAIADE
load_dotenv() # Populates the environment from .env.
client = LandingAIADE()
```
### Method 3: Set the API Key in a Notebook
In IPython-based notebooks (Jupyter, JupyterLab, Google Colab, or Kaggle), set the key for the current session with the `%env` magic command. The key is cleared when the kernel restarts, and it is visible in the notebook file if you share or commit it.
1. In a notebook cell, set the environment variable:
```python theme={null}
%env VISION_AGENT_API_KEY=
```
2. Initialize the client in a later cell:
```python theme={null}
from landingai_ade import LandingAIADE
client = LandingAIADE()
```
### API Key Precedence
If the API key is set in more than one place, the library resolves it in this order (the first match wins):
1. The `apikey` passed to the client constructor.
2. The `VISION_AGENT_API_KEY` environment variable, whether you set it directly or loaded it from a `.env` file. A value already set in your environment is not overridden by a `.env` file.
For help with missing-key errors, keys that fail to load, or keys that resolve to the wrong account, see [Troubleshoot API Key Issues](./agentic-api-key#troubleshoot-api-key-issues).
## Initialize the Client
Create a client. It reads `VISION_AGENT_API_KEY` from the environment automatically.
```python theme={null}
from landingai_ade import LandingAIADE
client = LandingAIADE()
```
By default, the library uses the US endpoints. If your API key is from the EU region, set the `environment` parameter to `eu`. API keys are region-specific: an EU key works only with the EU environment.
```python theme={null}
from landingai_ade import LandingAIADE
client = LandingAIADE(environment="eu")
```
For more about using Agentic Document Extraction in the EU, see [European Union (EU)](./eu).
## Parse a Document
Use `client.v2.parse_jobs` to convert a document into Markdown, a structure tree, and per-element grounding. The sub-client exposes `create`, `get`, `list`, and `wait`. The `wait` method polls until the job reaches a terminal state and returns the finished job.
Pass a local file as a `Path` with the `document` parameter, or a remote file with `document_url`. Setting `service_tier` to `standard` runs the job in the lane that consumes half the credits of `priority`.
A finished job carries the parse output in `result`, a `V2ParseResponse` with `markdown`, `structure`, and `metadata`. For the full workflow and parameters, see [Parse Asynchronously](./parse-async).
```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",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
## Extract Data
Use `client.v2.extract_jobs` to pull structured fields from parsed Markdown. Provide the Markdown as a string with `markdown` (or a remote URL with `markdown_url`) and a schema. The `schema` parameter accepts a Pydantic model, a dictionary, or a JSON string.
A finished job carries the extraction in `result`, a `V2ExtractResult` with `extraction`, `extraction_metadata`, `markdown`, and `metadata`. For the full workflow and parameters, see [Asynchronous Extraction](./extract-async).
```python theme={null}
from pathlib import Path
from pydantic import BaseModel, Field
from landingai_ade import LandingAIADE
class Financials(BaseModel):
revenue: str = Field(description="Q1 2024 revenue")
client = LandingAIADE()
# Parse first to get Markdown, then extract.
parse_job = client.v2.parse_jobs.create(
document=Path("document.pdf"),
model="dpt-3-pro-latest",
service_tier="standard",
)
parsed = client.v2.parse_jobs.wait(parse_job.job_id)
extract_job = client.v2.extract_jobs.create(
markdown=parsed.result.markdown,
schema=Financials,
service_tier="standard",
)
extracted = client.v2.extract_jobs.wait(extract_job.job_id)
print(extracted.result.extraction)
```
## Set the Model Version
The `model` parameter is optional. When you omit it, the API uses the latest DPT-3 Pro model. To select a family or pin a version, pass a model string such as `dpt-3-verity`, or a dated snapshot. See [Parsing Models](./parse-models).
Responses parsed with `dpt-3-verity` include a `confidence` score on each word-level `atomic_grounding` entry. See [Word Confidence Scores](./parse-response#word-confidence-scores-dpt-3-verity).
```python theme={null}
from pathlib import Path
job = client.v2.parse_jobs.create(
document=Path("document.pdf"),
model="dpt-3-pro-latest",
service_tier="standard",
)
```
## Save Output to a File
The job `create` methods do not accept `save_to`. To keep a job's output, write `result` to a file yourself, or pass `output_save_url` on `create` to have Agentic Document Extraction deliver the result straight to your own storage. See [Save Parsed Output to a URL](./parse-async#save-parsed-output-to-a-url).
The synchronous `parse` and `extract` methods take an optional `save_to` parameter instead, which writes the full response to a JSON file. Pass it a directory to use an auto-generated file name, or a path ending in `.json` to choose the exact file.
```python theme={null}
from pathlib import Path
job = client.v2.parse_jobs.create(
document=Path("document.pdf"),
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
Path("parse-output.json").write_text(done.result.model_dump_json(indent=2))
```
## Handle Errors
The synchronous `parse` and `extract` methods raise `V2SyncTimeoutError` if the request exceeds the server's synchronous time limit (HTTP 504). For large documents, use the async jobs interface instead.
When a parse partially succeeds (some pages fail), the API returns the full response with an HTTP 206 status, and the failed pages are listed in `metadata`. See [Troubleshoot Parsing](./parse-troubleshoot).
The job `wait` method returns the finished job regardless of outcome, so check `job.status`. To raise instead when a job fails, pass `raise_on_failure=True`, which raises `JobFailedError`. If a job does not finish within the `timeout`, `wait` raises `JobWaitTimeoutError`.
```python theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE
from landingai_ade.lib.v2_errors import JobFailedError, JobWaitTimeoutError
client = LandingAIADE()
job = client.v2.parse_jobs.create(
document=Path("document.pdf"),
service_tier="standard",
)
try:
done = client.v2.parse_jobs.wait(job.job_id, timeout=600, raise_on_failure=True)
print(done.result.markdown)
except JobFailedError as error:
print(f"Job failed: {error}")
except JobWaitTimeoutError:
print("Job did not finish in time; poll again with parse_jobs.get().")
```
## Additional Resources
* [Python library on GitHub](https://github.com/landing-ai/ade-python). The README covers client configuration not documented here, including retries, timeouts, the async client, logging, raw response access, and custom requests.
* [API reference](https://docs.landing.ai/api-reference/parse/ade-parse)
* [Parse Documents](./parse) and [Extract Data](./extract)
# TypeScript Library
Source: https://docs.landing.ai/dpt3/ade-typescript
Process documents using the ADE TypeScript library.
The [ade-typescript](https://github.com/landing-ai/ade-typescript) library wraps the Agentic Document Extraction APIs so you can parse and extract documents from TypeScript and JavaScript. The library is published as the `landingai-ade` package and generated from the API specification.
The Gen2 APIs live under the `client.v2` sub-client. It exposes both processing modes: async jobs through `client.v2.parseJobs` and `client.v2.extractJobs`, and synchronous calls through `client.v2.parse` and `client.v2.extract`. Jobs accept larger documents, default to the lower-consumption `standard` service tier, and suit automated pipelines and background work. See [Sync vs Async Processing](./sync-async).
## Install the Library
```bash theme={null}
npm install landingai-ade
```
## Set Your API Key
The library reads your API key from the `VISION_AGENT_API_KEY` environment variable. [Generate an API key](./agentic-api-key) first, then set it using any of the methods below. Do not hard-code your API key in source files.
### Method 1: Set the API Key as an Environment Variable
1. Set the environment variable. To persist the key across sessions on macOS or Linux, add the `export` command to your shell profile (`.zshrc` or `.bashrc`), then run `source ~/.zshrc`.
```bash macOS/Linux theme={null}
export VISION_AGENT_API_KEY=""
```
```cmd Windows (Command Prompt) theme={null}
set "VISION_AGENT_API_KEY="
```
```powershell Windows (PowerShell) theme={null}
$env:VISION_AGENT_API_KEY=""
```
2. Initialize the client. It reads the `VISION_AGENT_API_KEY` environment variable automatically:
```typescript theme={null}
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE();
```
### Method 2: Store the API Key in a .env File
Store your API key in a `.env` file. The library reads the key from the environment; it does not load `.env` files on its own, so use the `dotenv` package to load the file.
1. Install the `dotenv` package:
```bash theme={null}
npm install dotenv
```
2. Create a `.env` file in your project root and add your API key:
```bash theme={null}
VISION_AGENT_API_KEY=
```
3. Load the `.env` file before you initialize the client:
```typescript theme={null}
import "dotenv/config"; // Loads .env into process.env.
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE();
```
In Node.js 20.6 or later, you can skip the `dotenv` package and run your script with `node --env-file=.env your-script.js`.
### API Key Precedence
If the API key is set in more than one place, the library resolves it in this order (the first match wins):
1. The `apikey` passed to the client constructor.
2. The `VISION_AGENT_API_KEY` environment variable, whether you set it directly or loaded it from a `.env` file. A value already set in your environment is not overridden by a `.env` file.
For help with missing-key errors, keys that fail to load, or keys that resolve to the wrong account, see [Troubleshoot API Key Issues](./agentic-api-key#troubleshoot-api-key-issues).
## Initialize the Client
Create a client. It reads `VISION_AGENT_API_KEY` from the environment automatically.
```typescript theme={null}
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE();
```
By default, the library uses the US endpoints. If your API key is from the EU region, set the `environment` option to `eu`. API keys are region-specific: an EU key works only with the EU environment.
```typescript theme={null}
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE({ environment: "eu" });
```
For more about using Agentic Document Extraction in the EU, see [European Union (EU)](./eu).
## Parse a Document
Use `client.v2.parseJobs` to convert a document into Markdown, a structure tree, and per-element grounding. The sub-client exposes `create`, `get`, `list`, and `wait`. The `wait` method polls until the job reaches a terminal state and returns the finished job.
Pass a local file as a read stream with the `document` parameter, or a remote file with `document_url`. Setting `service_tier` to `standard` runs the job in the lane that consumes half the credits of `priority`.
A finished job carries the parse output in `result`, a `V2ParseResponse` with `markdown`, `structure`, and `metadata`. For the full workflow and parameters, see [Parse Asynchronously](./parse-async).
```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",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
## Extract Data
Use `client.v2.extractJobs` to pull structured fields from parsed Markdown. Provide the Markdown as a string with `markdown` (or a remote URL with `markdown_url`) and a schema. The `schema` parameter accepts a JSON Schema object or a JSON string.
A finished job carries the extraction in `result`, a `V2ExtractResult` with `extraction`, `extraction_metadata`, `markdown`, and `metadata`. For the full workflow and parameters, see [Asynchronous Extraction](./extract-async).
```typescript theme={null}
import fs from "fs";
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE();
// Parse first to get Markdown, then extract.
const parseJob = await client.v2.parseJobs.create({
document: fs.createReadStream("document.pdf"),
model: "dpt-3-pro-latest",
service_tier: "standard",
});
const parsed = await client.v2.parseJobs.wait(parseJob.job_id);
const extractJob = await client.v2.extractJobs.create({
markdown: (parsed.result as LandingAIADE.V2ParseResponse).markdown,
schema: {
type: "object",
properties: {
revenue: { type: "string", description: "Q1 2024 revenue" },
},
},
service_tier: "standard",
});
const extracted = await client.v2.extractJobs.wait(extractJob.job_id);
console.log((extracted.result as LandingAIADE.V2ExtractResult).extraction);
```
To define a typed schema, use [Zod](https://zod.dev) (v4 or later) and pass `z.toJSONSchema(YourSchema)` as the `schema`.
## Set the Model Version
The `model` parameter is optional. When you omit it, the API uses the latest DPT-3 Pro model. To select a family or pin a version, pass a model string such as `dpt-3-verity`, or a dated snapshot. See [Parsing Models](./parse-models).
Responses parsed with `dpt-3-verity` include a `confidence` score on each word-level `atomic_grounding` entry. See [Word Confidence Scores](./parse-response#word-confidence-scores-dpt-3-verity).
```typescript theme={null}
import fs from "fs";
const job = await client.v2.parseJobs.create({
document: fs.createReadStream("document.pdf"),
model: "dpt-3-pro-latest",
service_tier: "standard",
});
```
## Save Output to a File
The job `create` methods do not accept `saveTo`. To keep a job's output, write `result` to a file yourself, or pass `output_save_url` on `create` to have Agentic Document Extraction deliver the result straight to your own storage. See [Save Parsed Output to a URL](./parse-async#save-parsed-output-to-a-url).
The synchronous `parse` and `extract` methods take an optional `saveTo` parameter instead, which writes the full response to a JSON file. Pass it a directory to use an auto-generated file name, or a path ending in `.json` to choose the exact file.
```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"),
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
fs.writeFileSync("parse-output.json", JSON.stringify(done.result as LandingAIADE.V2ParseResponse, null, 2));
```
## Handle Errors
The synchronous `parse` and `extract` methods throw `V2SyncTimeoutError` if the request exceeds the server's synchronous time limit (HTTP 504). For large documents, use the async jobs interface instead.
When a parse partially succeeds (some pages fail), the API returns the full response with an HTTP 206 status, and the failed pages are listed in `metadata`. See [Troubleshoot Parsing](./parse-troubleshoot).
The job `wait` method returns the finished job regardless of outcome, so check `job.status`. To throw instead when a job fails, pass `raiseOnFailure: true`, which throws `JobFailedError`. If a job does not finish within the `timeout`, `wait` throws `JobWaitTimeoutError`. These v2 helper errors do not extend `APIError`, so catch them by name.
```typescript theme={null}
import fs from "fs";
import LandingAIADE, { JobFailedError, JobWaitTimeoutError } from "landingai-ade";
const client = new LandingAIADE();
const job = await client.v2.parseJobs.create({
document: fs.createReadStream("document.pdf"),
service_tier: "standard",
});
try {
const done = await client.v2.parseJobs.wait(job.job_id, { timeout: 600000, raiseOnFailure: true });
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
} catch (error) {
if (error instanceof JobFailedError) {
console.error(`Job failed: ${error.message}`);
} else if (error instanceof JobWaitTimeoutError) {
console.error("Job did not finish in time; poll again with parseJobs.get().");
} else {
throw error;
}
}
```
## Additional Resources
* [TypeScript library on GitHub](https://github.com/landing-ai/ade-typescript). The README covers client configuration not documented here, including retries, timeouts, logging, raw response access, and customizing the fetch client.
* [API reference](https://docs.landing.ai/api-reference/parse/ade-parse)
* [Parse Documents](./parse) and [Extract Data](./extract)
# Parse Documents
Source: https://docs.landing.ai/dpt3/parse
Parse documents with the Parse API into Markdown, structured blocks, and per-block grounding.
The [Parse API](https://docs.landing.ai/api-reference/parse/ade-parse) converts a document into structured data for retrieval-augmented generation (RAG), search, extraction, or any downstream workflow. It returns a reading-order Markdown rendering of the document, a hierarchical structure of its pages and blocks, and per-block grounding that maps everything back to the source.
## How Parse Works
You send a PDF, image, or Office document to the parse endpoint, optionally choosing a [parsing model](./parse-models) and customizing the parse with [options](./parse-input#request-options). The API returns a single JSON response containing the reading-order Markdown, the document structure, per-block grounding, and request metadata. See [Parse API Response](./parse-response) for the field-by-field reference.
If you haven't made an API call yet, start with the [Quickstart](./quickstart) to get a real response to follow along with.
## Call the Parse API
Send a document to the parse endpoint with a POST request. Replace `YOUR_API_KEY` with your [API key](./agentic-api-key) and `document.pdf` with the path to your file.
The [`options`](./parse-input#request-options) field is optional: the defaults suit most documents, so include it only to customize the parse (here, to process specific pages).
```bash cURL theme={null}
curl -X POST 'https://api.ade.landing.ai/v2/parse' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'document=@document.pdf' \
-F 'model=dpt-3-pro-latest' \
-F 'options={"pages":[1]}'
```
```python Python theme={null}
from pathlib import Path
from landingai_ade import LandingAIADE
client = LandingAIADE()
response = client.v2.parse(
document=Path("document.pdf"),
model="dpt-3-pro-latest",
options={"pages": [1]},
)
print(response.markdown)
```
```typescript TypeScript theme={null}
import fs from "fs";
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE();
const response = await client.v2.parse({
document: fs.createReadStream("document.pdf"),
model: "dpt-3-pro-latest",
options: { pages: [1] },
});
console.log(response.markdown);
```
For the full request and response contract, see the [API reference](https://docs.landing.ai/api-reference/parse/ade-parse).
# Parse Input Parameters
Source: https://docs.landing.ai/dpt3/parse-input
Set the document, model version, and options when calling the Parse API.
The Parse API accepts a document, an optional model, and an optional `options` object. The same core fields work whether you [call it synchronously](https://docs.landing.ai/api-reference/parse/ade-parse) or create a [Parse Job](./parse-async), which takes a few additional parameters of its own.
## Sample Request
Create a [Parse Job](./parse-async) on the `standard` service tier, then collect the parse results from the finished job. Replace `YOUR_API_KEY` with your [API key](./agentic-api-key) and `document.pdf` with the path to your file.
```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 'options={"pages":[1]}' \
-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",
options={"pages": [1]},
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
```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",
options: { pages: [1] },
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
## Parameters
| Parameter | Required | Description |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document` | Conditional | The document to parse (PDF, image, or Office document), sent as an uploaded file. Provide either `document` or `document_url`. |
| `document_url` | Conditional | A public URL that the API fetches the document from. Provide either `document` or `document_url`. |
| `model` | No | The parsing model family and snapshot. Defaults to the latest DPT-3 Pro snapshot. See [Model Version](#model-version). |
| `options` | No | A JSON object of optional settings. See [Request Options](#request-options). |
| `service_tier` | No | Parse Jobs only: the tier the job runs on, either `standard` or `priority`. Defaults to `standard`. See [Choose a Service Tier](./parse-async#choose-a-service-tier). |
| `output_save_url` | No | Parse Jobs only: a presigned URL the job delivers its output to, instead of returning it in `result`. See [Save Parsed Output to a URL](./parse-async#save-parsed-output-to-a-url). |
## Model Version
The `model` form field selects the parsing model family and snapshot:
* `dpt-3-pro`: the highest-quality model. Default.
* `dpt-3-verity`: the lower-latency model for digitally created text documents. In preview.
Requests that omit `model` use the latest DPT-3 Pro snapshot, and the response reports the resolved version in [`metadata.model_version`](./parse-response#metadata). For the full comparison, all accepted values, and guidance on pinning snapshots, see [Parsing Models](./parse-models).
For example, this request selects the latest DPT-3 Pro snapshot:
```bash cURL highlight={4} 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'
```
## Request Options
The optional `options` form field is a JSON object that customizes the response. All fields are optional; omitted fields take the defaults shown.
| Field | Type | Default | Description |
| ------------------------ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pages` | `int[]` | `null` | 1-indexed page numbers to process. `null` processes all pages. Page numbers below 1 or beyond the document's last page return HTTP 422, and a single invalid value rejects the whole request. Skipped pages are absent from `structure.children`, and the Markdown has no gap marker; check each page's `grounding.page` to identify missing pages. |
| `blocks..markdown` | `bool` | `true` | Whether to include the block type's content in the Markdown. Applies to `text`, `table`, `figure`, `marginalia`, `attestation`, `logo`, `scan_code`, and `card`. When `false`, visual types (`figure`, `logo`, `scan_code`, `card`, `attestation`) emit only a header line such as `> [!FIGURE]`; `text`, `table`, and `marginalia` emit nothing. Suppressed blocks still appear in `structure`, with a zero-length `range` and an empty `atomic_grounding` array. |
| `blocks.table.format` | `"markdown"` or `"html"` | `"html"` | Table representation in the Markdown output. HTML preserves merged cells that pipe syntax cannot; `markdown` uses pipe syntax. |
| `atomic_grounding` | `bool` | `true` | Whether to include the fine-grained `atomic_grounding` array on leaf blocks. Set `false` to omit the field from every node. On DPT-3 Verity, this also removes every `confidence` score, because the scores live on the word entries. |
| `inline_markdown` | `bool` | `false` | When `true`, every structure node (the document root, each page, and each block, including table cells) carries its own `markdown` field with its slice of the top-level Markdown, so you don't have to slice by `range` yourself. Entries in `atomic_grounding` do not carry it. |
| `password` | `string` | `null` | Not currently supported: encrypted PDFs are rejected, and providing a password returns HTTP 422. Decrypt the file and upload an unencrypted copy. |
### Example Options
The following examples all parse the same sample calibration report, so you can see exactly what each option changes.
For the complete, unmodified output, download the full default response (parsed with no options).
Each example shows the full request with the relevant `options` line highlighted, followed by a trimmed view of the parse results the finished job returns in `result`.
#### Process Specific Pages
Pass `pages` to parse only the pages you need. Page numbers are 1-indexed: `1` is the document's first page. `metadata.page_count` still reports the full document length, while `structure.children` returns only the requested pages.
```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=@calibration-report.pdf' \
-F 'model=dpt-3-pro-latest' \
-F 'options={"pages":[1,3]}' \
-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("calibration-report.pdf"),
model="dpt-3-pro-latest",
options={"pages": [1, 3]},
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
```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("calibration-report.pdf"),
model: "dpt-3-pro-latest",
options: { pages: [1, 3] },
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
When you get the parse results, `page_count` counts all pages but `structure.children` holds only pages 1 and 3:
```json theme={null}
{
"metadata": {
"page_count": 3,
"failed_pages": []
// ...
},
"structure": {
"type": "document",
"children": [
{
"type": "page",
"grounding": { "page": 1, "range": { "start": 0, "end": 1695 }, "box": { "xmin": 0, "ymin": 0, "xmax": 1, "ymax": 1 } },
"status": "ok",
"children": [ /* ... */ ]
},
{
"type": "page",
"grounding": { "page": 3, "range": { "start": 1716, "end": 3224 }, "box": { "xmin": 0, "ymin": 0, "xmax": 1, "ymax": 1 } },
"status": "ok",
"children": [ /* ... */ ]
}
]
}
}
```
#### Render Tables as Markdown
Tables are returned as HTML by default. HTML preserves merged cells and nested layouts that pipe syntax cannot represent, such as the `Measured Value` header spanning the `As Found` and `As Left` columns in this calibration table:
```html theme={null}
```
Set `blocks.table.format` to `markdown` to receive tables as pipe-syntax Markdown instead. Merged cells expand into empty adjacent cells:
```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=@calibration-report.pdf' \
-F 'model=dpt-3-pro-latest' \
-F 'options={"blocks":{"table":{"format":"markdown"}}}' \
-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("calibration-report.pdf"),
model="dpt-3-pro-latest",
options={"blocks": {"table": {"format": "markdown"}}},
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
```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("calibration-report.pdf"),
model: "dpt-3-pro-latest",
options: { blocks: { table: { format: "markdown" } } },
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
When you get the parse results, the `markdown` field carries the same table in pipe syntax, with the merged header flattened into empty cells:
```markdown theme={null}
| Test Point | Nominal (V) | Measured Value (V) | | As-Found Deviation (mV) | Tolerance (±mV) | Result |
|---|---|---|---|---|---|---|
| | | As Found | As Left | | | |
| TP-1 | 0.000 | 0.001 | 0.000 | +1 | 5 | Pass |
| TP-2 | 2.500 | 2.503 | 2.500 | +3 | 10 | Pass |
| TP-3 | 5.000 | 5.041 | 5.002 | +41 | 20 | Fail |
| TP-4 | 7.500 | 7.512 | 7.503 | +12 | 30 | Pass |
| TP-5 | 10.000 | 10.018 | 10.004 | +18 | 40 | Pass |
```
#### Suppress a Block Type
Set a block type's `markdown` option to `false` to drop its content from the `markdown`. Suppressing a block type also speeds up parsing, because suppressed blocks skip model captioning. Here, figures are suppressed, so each figure collapses to a `> [!FIGURE]` header line. The figure still appears in `structure`, with a zero-length `range` and an empty `atomic_grounding` array.
```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=@calibration-report.pdf' \
-F 'model=dpt-3-pro-latest' \
-F 'options={"blocks":{"figure":{"markdown":false}}}' \
-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("calibration-report.pdf"),
model="dpt-3-pro-latest",
options={"blocks": {"figure": {"markdown": False}}},
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
```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("calibration-report.pdf"),
model: "dpt-3-pro-latest",
options: { blocks: { figure: { markdown: false } } },
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
When you get the parse results, the `markdown` field shows each figure as a header line instead of its content:
```markdown theme={null}
AS-FOUND DEVIATION BY TEST POINT
> [!FIGURE]
```
#### Omit Atomic Grounding
Set `atomic_grounding` to `false` to drop the fine-grained `atomic_grounding` array from every block, leaving only the block-level `grounding`. Use this to reduce response size when you don't need the fine-grained coordinates.
```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=@calibration-report.pdf' \
-F 'model=dpt-3-pro-latest' \
-F 'options={"atomic_grounding":false}' \
-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("calibration-report.pdf"),
model="dpt-3-pro-latest",
options={"atomic_grounding": False},
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
```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("calibration-report.pdf"),
model: "dpt-3-pro-latest",
options: { atomic_grounding: false },
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
When you get the parse results, each block carries only its block-level grounding, and the `atomic_grounding` field is omitted entirely:
```json theme={null}
{
"type": "text",
"id": "text-8",
"grounding": {
"page": 1,
"range": { "start": 720, "end": 1169 },
"box": { "xmin": 0.0902, "ymin": 0.36545, "xmax": 0.9281, "ymax": 0.45273 }
}
}
```
#### Include Markdown on Each Node
Set `inline_markdown` to `true` to add each node's slice of the document Markdown as a `markdown` field on the node itself, so you can read a block's text without slicing the top-level string by `range`.
```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=@calibration-report.pdf' \
-F 'model=dpt-3-pro-latest' \
-F 'options={"inline_markdown":true}' \
-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("calibration-report.pdf"),
model="dpt-3-pro-latest",
options={"inline_markdown": True},
service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)
```
```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("calibration-report.pdf"),
model: "dpt-3-pro-latest",
options: { inline_markdown: true },
service_tier: "standard",
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as LandingAIADE.V2ParseResponse).markdown);
```
When you get the parse results, every structure node (document, page, block, and table cell) carries its `markdown` slice. Entries in `atomic_grounding` do not. To get an entry's text, slice by its `range` or read the parent block's `markdown`:
```json theme={null}
{
"type": "text",
"id": "text-0",
"grounding": {
"page": 1,
"range": { "start": 0, "end": 27 },
"box": { "xmin": 0.08007, "ymin": 0.02051, "xmax": 0.7402, "ymax": 0.05965 }
},
"markdown": "**Report No.** TVL-CAL-7731"
}
```
# Parsing Models
Source: https://docs.landing.ai/dpt3/parse-models
Choose between DPT-3 Pro and DPT-3 Verity, and pin a model snapshot for consistent parsing results.
A **Document Pre-Trained Transformer** (DPT) is the model that powers the [Parse API](./parse). The model identifies a document's layout, transcribes the content into Markdown in reading order, and records where every block sits on the page.
The Parse API has two model families:
* **DPT-3 Pro** delivers the highest parsing quality. This is the default model.
* **DPT-3 Verity** parses digitally created text documents with lower latency and lower credit consumption. This model is in preview.
Set the model with the `model` parameter on [Parse](./parse) and [Parse Jobs](./parse-async) requests. Requests that omit `model` use the latest DPT-3 Pro snapshot.
## DPT-3 Pro vs. DPT-3 Verity
DPT-3 Pro and DPT-3 Verity both run on the same endpoints, accept the same [file types](./file-types), and return the same [response shape](./parse-response).
They differ in what they read and what they return: DPT-3 Pro handles more document styles and content types, while DPT-3 Verity returns results faster, consumes fewer credits, and adds per-word confidence scores.
| Capability | DPT-3 Verity | DPT-3 Pro |
| -------------------------------------------------------- | -------------------------------------------- | --------- |
| Scanned documents and handwriting | No | Yes |
| Non-Latin scripts and math formulas | No | Yes |
| Text and marginalia | Yes | Yes |
| Tables | Yes | Yes |
| Checkboxes | Yes | Yes |
| Key-value pairs and form layouts | Less accurate | Yes |
| Figure descriptions | Basic | Detailed |
| Attestation, card, and scan code labels | Yes | Yes |
| Markdown formatting (headings, bold, underline, italics) | No | Yes |
| Atomic grounding granularity | Word | Line |
| Confidence scores | Word level, for text, tables, and marginalia | No |
### DPT-3 Pro
DPT-3 Pro is the default model and the right choice for most workloads. Use it for scanned or handwritten documents, non-Latin scripts, math formulas, and complex forms. It generates detailed descriptions for figures, formats the Markdown output with headings, bold, underline, and italics, and grounds text down to the visual line.
### DPT-3 Verity
DPT-3 Verity is optimized for digitally created text documents, such as generated PDFs and Office files, and has lower latency than DPT-3 Pro.
In the Markdown output, it often renders the bracketed descriptions of visual content (logos, scan codes, and the visual marks in attestations) as generic markers such as `[VISUAL_TEXT]` rather than descriptive phrases.
DPT-3 Verity grounds text, marginalia, and table cells at the word level: the `atomic_grounding` array has one entry per word, and each entry carries a `confidence` value between 0 and 1 that reflects how certain the model is that it transcribed the word correctly. See [Atomic Grounding](./parse-response#atomic-grounding).
DPT-3 Verity consumes fewer credits than DPT-3 Pro. For rates, see [Credit Consumption](./credit-consumption#parse).
**DPT-3 Verity was renamed from DPT-3 Fast.** Requests that pin the earlier `dpt-3-fast` values keep working, so no code change is required.
## Model Versions and Snapshots
The following table lists the available `model` values for [Parse](./parse) and [Parse Jobs](./parse-async):
| Value | Behavior |
| ------------------------------- | ----------------------------------------------------------------- |
| `dpt-3-pro-latest` | The latest snapshot of DPT-3 Pro. This is the default. |
| `dpt-3-pro` | Alias for `dpt-3-pro-latest`. |
| `dpt-3-pro-20260710` | The snapshot of DPT-3 Pro generated on July 10, 2026. |
| `dpt-3-verity-latest` | The latest snapshot of DPT-3 Verity. |
| `dpt-3-verity` | Alias for `dpt-3-verity-latest`. |
| `dpt-3-verity-20260804-preview` | The preview snapshot of DPT-3 Verity generated on August 4, 2026. |
Some snapshots have been superseded: a newer snapshot replaced them, and they no longer appear in the table above. If you pin a superseded snapshot, your requests still succeed. The API resolves the name to the current snapshot and reports the current version in `metadata.model_version`. Update pinned code to a value from the table.
### Why Model Versioning Matters
When integrating the API, you have two options for specifying the model:
1. **Use a general model name** (like `dpt-3-pro` or `dpt-3-pro-latest`) to always get the newest version. This automatically gives you improvements and updates, but parsing results may change when new model versions are released.
2. **Use a specific snapshot** (like `dpt-3-pro-20260710`) to pin to an exact model version. Your results stay consistent for as long as the snapshot is available, but you won't receive improvements.
If you use only a general model name like `dpt-3-pro` in production, your application may produce different results when we release model updates. Consider whether you need consistent results or prefer to receive the latest improvements.
### Understanding Snapshots and -latest
**Snapshots** are frozen versions of a model released on specific dates. A snapshot's parsing behavior never changes while it is available, making your results predictable. When a snapshot is superseded, its name resolves to the current snapshot instead of failing.
The **latest** suffix always points to the most recent snapshot of that model family, and the bare family name is equivalent to `-latest`. Whichever form you send, the response reports the snapshot that actually ran in `metadata.model_version`, so pinned code can detect a change.
## Set the Model
Supply the value in the `model` form field on the request. For the full request reference, see [Parse Input Parameters](./parse-input). To set the model in the Python and TypeScript libraries, see [Python Library](./ade-python) and [TypeScript Library](./ade-typescript). To select the model in the [Playground](./playground), use the model drop-down menu.
For example, this request creates a Parse Job that uses the latest DPT-3 Pro snapshot:
```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' \
-F 'service_tier=standard'
```
# Parse API Response
Source: https://docs.landing.ai/dpt3/parse-response
Read the Parse response: reading-order Markdown, document structure with per-block grounding, and metadata.
A successful parse returns a JSON object with the reading-order Markdown, the document structure with per-block grounding, and request metadata.
## The Response Shape
The response contains these top-level fields:
| Field | Description |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`markdown`](#markdown) | The complete document as a single Markdown string, in reading order. |
| [`metadata`](#metadata) | Information about the job: model version, page count, duration, billing, and more. |
| [`structure`](#structure-pages-and-blocks) | A `document` node whose `children` are pages. Each page's `children` are the blocks detected on that page. Every node below the root carries its location inline in a [`grounding`](#grounding-where-things-are) object. |
## Markdown
The `markdown` field is a single string containing the document in reading order, following [CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/) with a few extensions. Use it directly for RAG, search indexing, or anything that takes Markdown as input. Every `range` elsewhere in the response points into this string, using Unicode code point offsets as declared by [`metadata.range_units`](#metadata).
Superscript and subscript text that is not part of a math formula is wrapped in `` and `` tags.
When using [DPT-3 Pro](./parse-models), math formulas are transcribed as LaTeX, wrapped in `$...$` for inline math or `$$...$$` for display math, matching the original layout.
| Block | Representation |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page break | `` appended after each page's content. Absent in single-page documents. |
| Document ID | `` appended as the final line of the output. It carries the parse job's `job_id` so the [Extract API](./extract) can link an extract call back to the originating parse job. |
| Table | HTML `` markup by default, which preserves merged cells. Use `options.blocks.table.format="markdown"` to emit pipe syntax instead; merged cells then expand into empty adjacent cells. |
| Figure | An HTML-style figure element carrying a classification label: `
| Test Point | Nominal (V) | Measured Value (V) | As-Found Deviation (mV) | Tolerance (±mV) | Result | |
| As Found | As Left | |||||
| TP-1 | 0.000 | 0.001 | 0.000 | +1 | 5 | Pass |
| TP-2 | 2.500 | 2.503 | 2.500 | +3 | 10 | Pass |
| TP-3 | 5.000 | 5.041 | 5.002 | +41 | 20 | Fail |
| TP-4 | 7.500 | 7.512 | 7.503 | +12 | 30 | Pass |
| TP-5 | 10.000 | 10.018 | 10.004 | +18 | 40 | Pass |
## Review the Results
The parse results open in the Parse tab of the project view:
* **Markdown view (default):** The reading-order Markdown rendering of your document. Use this for quick visual review or to copy into a downstream tool.
* **JSON view:** The full response payload. Use this view to inspect block ids, ranges, and grounding coordinates. To collapse or expand a nested section, hover over the narrow column along the left edge of the JSON and click the arrow that appears.
* **Click a block** in either view to highlight its bounding box on the document preview on the left.
* Use the **Search**, **Download**, and **Copy** buttons in the toolbar above the result to find text in the current view, save it, or paste it elsewhere.
* Click **Display** in the toolbar to change how results render: **Always show atomic grounding** keeps the fine-grained grounding boxes visible on the document preview, and **Word wrap** wraps long lines in the JSON view.
For a complete reference on what each response field contains, see [Parse API Response](./parse-response).
## Review Word Confidence Scores (DPT-3 Verity)
When you parse with [DPT-3 Verity](./parse-models), every word in text, tables, and marginalia carries a [confidence score](./parse-response#word-confidence-scores-dpt-3-verity).
### Spot Low-Confidence Words
The parse result highlights every word whose score falls below the [confidence threshold](#confidence-settings-in-the-display-menu). Hover over a highlighted word to see its score. Each block also shows its lowest word score (for example, `min 0.683`).
### Confidence Settings in the Display Menu
Open the **Display** menu on the Parse tab to adjust the highlighting:
* **Highlight low confidence:** Show or hide the highlights. On by default, and available only for parses that include confidence scores.
* **Threshold:** Set the score that counts as low confidence (default 95%). The highlights update as you change it.
* **Show low-confidence blocks only:** Filter the results panel to blocks that contain at least one word below the threshold.
## Customize the Parse Output with Config
To change how DPT-3 parses your files, open the **Config** drop-down menu on the Parse tab and update the settings. These controls set the same values as the API's [`options` field](./parse-input#request-options).
After you adjust the options, click **Apply to all files** to reparse with the new settings.
* **Captioning options:** Choose which block types are included in the Markdown (Text, Table, Figure, Marginalia, Attestation, Logo, Scan code, and Card). All are on by default. Clearing one drops that block type's content from the Markdown, but the block still appears in the JSON structure and grounding.
* **Table output format:** Choose **HTML** (default) or **Markdown** for how tables appear in the Markdown output. This control appears only while **Table** captioning is on.
* **Atomic grounding:** Include the fine-grained grounding detail (the `atomic_grounding` array) with each block: per-line with DPT-3 Pro, per-word with DPT-3 Verity. On by default.
* **Pages:** Enter the pages to parse (for example, `1-3`) to process only part of the document. The Playground and the API's `options.pages` field both use 1-based page numbers.
# Extract Data
Source: https://docs.landing.ai/dpt3/extract
Pull specific fields from Markdown with a schema for high-volume, repeatable extraction.
Use the redesigned Extract API to pull specific data fields from a document. You provide a Markdown representation of the document and a schema that defines the fields you want, and the API returns their values in a structured, predictable format along with the location of each value in the source Markdown.
The Extract API suits high-volume, repeatable workflows: use it when you need the same set of fields from many documents, such as invoice totals, contract dates, or form field values. Results stay consistent across documents with varying layouts because extraction is schema-driven.
## How Extract Works
The Extract API works on a Markdown string. That Markdown can come from any source: the [Parse API](https://docs.landing.ai/api-reference/parse/ade-parse), a third-party parser, a web scraper, or a hand-authored document. For the best results, use Markdown produced by the Parse API, which preserves the document's reading order and structure and links each extraction back to its parse job.
You pass the Markdown and a schema to the endpoint. The API returns the extracted values, per-field range grounding that points back into the source Markdown, and request metadata. To turn those ranges into visual locations (the blocks, page numbers, and bounding boxes each value came from), pass the results to the [Ground API](./ground).
## Sample Request
Send the Markdown and a schema to the extract endpoint with a POST request. Replace `YOUR_API_KEY` with your [API key](./agentic-api-key) and `parse-output.md` with the path to your Markdown file.
| Parse and Extract (synchronous) | Parse Jobs and Extract Jobs (asynchronous) | ||
|---|---|---|---|
| Service tier | Priority | Standard (default) | |
| Best for | Interactive workflows: a person or agent is waiting on the result | Time-sensitive work that a synchronous request can't handle: files over the synchronous size cap, or when you don't want to hold a connection open | Work with no one waiting: automated pipelines, background agent steps, scheduled ingestion, and the largest documents |
| How you get the result | Inline in the response | Poll the job, or save the output to a URL | Poll the job, or save the output to a URL |
| Estimated turnaround time | Seconds to minutes | Seconds to minutes | Minutes to hours |
| Timeout limit | 475 seconds | 6 hours | 6 hours |
| Credit consumption | Full rate | Full rate | Half the priority rate |
| Parse limits per request | 6,000 pages; 50 MiB | 6,000 pages; 1 GiB for PDFs, 50 MiB for images | 6,000 pages; 1 GiB for PDFs, 50 MiB for images |
| Largest single document (Parse) | Your plan's per-minute page limit: 100 pages (Explore), 200 (Team). Enterprise limits are custom. | 6,000 pages | |
| Parse rate limit | Per-minute limit shared across all priority work, refilling continuously |
Hourly limit, resetting each hour | |
| Extract limits per request | No input size limit | No input size limit | No input size limit |
| Extract rate limit | Based on your plan and the input Markdown size | None: jobs are accepted immediately and paced internally | None: jobs are accepted immediately and paced internally |
| File Type | Playground | API |
|---|---|---|
| Images | ||
| JPEG | ||
| JPG | ||
| PNG | ||
| GIF | ||
| BMP | ||
| TIFF | ||
| TIF | ||
| WEBP | ||
| Text Documents (see notes [here](#file-conversion-for-text-documents-and-presentations)) |
||
| DOCX (Word) | ||
| ODT (OpenDocument Text) | ||
| RTF (Rich Text Format) | ||
| Presentations (see notes [here](#file-conversion-for-text-documents-and-presentations)) |
||
| PPTX (PowerPoint) |
## Delete Account
To delete your Agentic Document Extraction account, send an email with your request to [support@landing.ai](mailto:support@landing.ai). Use the email address you used to sign up for Agentic Document Extraction.
# Security and Privacy
Source: https://docs.landing.ai/dpt3/ade-security
Review ADE security practices, zero data retention, and compliance certifications (GDPR, SOC 2, HIPAA).
LandingAI is committed to protecting your data and maintaining the highest security standards for Agentic Document Extraction.
Refer to the resources below to learn about our security practices, zero data retention (ZDR) option, compliance certifications (GDPR, SOC 2 Type II, HIPAA), and more.
(us-east-2) | | EU | AWS Ireland
(eu-west-1) | ### Scope When ZDR is enabled, our fully managed SaaS offering ensures zero data retention across the entire platform, including all subprocessors. When ZDR is enabled, ZDR is applicable when parsing documents with our Python libraries and when calling the ADE APIs directly. The [Ground API](/dpt3/ground) is the exception: it is not available while ZDR is enabled, and requests to it return a 501 error. A separate setting controls whether ZDR is applied to the [Playground](https://ade.landing.ai/). ### Result Retention Results are kept only until you receive them. Specific retention functionality depends on what generation of the API you're using: * [Gen2 APIs](#gen2-apis) * [Gen1 APIs](#gen1-apis) #### Gen2 APIs Every result from the [Gen2 APIs](/dpt3/overview) is deleted as soon as you receive it, no matter how you call the API. A result can be retrieved once. If you need it again, rerun the request. | How you call the API | What happens to the result | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Synchronous [Parse](/dpt3/parse) and [Extract](/dpt3/extract) requests | Returned in the response. Nothing is retained after the response is sent. | | [Parse Jobs](/dpt3/parse-async) and [Extract Jobs](/dpt3/extract-async) | Deleted as soon as you fetch it. For a job, the first poll that returns the completed result is the fetch. A result you never fetch is deleted automatically, no less than 24 hours and no longer than 48 hours after the job completes. | | [Parse Jobs](/dpt3/parse-async) and [Extract Jobs](/dpt3/extract-async) created with `output_save_url` | Delivered to your storage, then deleted immediately. | #### Gen1 APIs The [Gen1 APIs](./ade-overview) never hold a result for later pickup: | How you call the API | What happens to the result | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Synchronous [Parse](./parse) and [Extract](./ade-extract) requests | Returned in the response. Nothing is retained after the response is sent. | | [Parse Jobs](./ade-parse-async) and [Extract Jobs](./ade-extract-async) | Delivered to your storage and never retained. ZDR requires the URL input parameter and the `output_save_url` parameter on every job. See the ZDR Requirements for [Parse Jobs](./ade-parse-async#zdr-requirements) and [Extract Jobs](./ade-extract-async#zdr-requirements). | ### Enable ZDR Users on the Team and Enterprise plans can enable ZDR in the user interface by following the instructions below: 1. Log in to [https://ade.landing.ai/](https://ade.landing.ai/). 2. Go to the [Organization Settings](https://ade.landing.ai/settings/organization/general) page (to navigate there manually, click your profile icon at the bottom left corner of the page and click **Organization Settings**). 3. In the Zero Data Retention box, click **Turn It On**. 4. A pop-up opens. Carefully read the information so that you understand how ZDR works. 5. If you want ZDR to also be applied when uploading documents to the [Playground](https://ade.landing.ai/), select the **Also apply to Playground UI** checkbox. 6. Click **Enable Zero Data Retention**. 7. The Zero Data Retention box confirms that ZDR is enabled. 8. If you need to ensure HIPAA compliance, you must have a Business Associate Agreement (BAA) in place with LandingAI. To initiate the BAA process, submit your request through the form on the [Organization Settings](https://ade.landing.ai/settings/organization/general) page (available after ZDR is enabled).
| Action | Developer | Admin |
|---|---|---|
| Process documents | ||
| Create API keys | ||
| Revoke your own API keys | ||
| Revoke API keys other members created | ||
| Invite members | ||
| Remove members | ||
| Change member roles | ||
| Manage billing | ||
| Update organization name |
**Example**: Okta, Microsoft Entra ID, etc. | | JIT provisioning preference | Whether you want to enable Just-in-Time (JIT) provisioning for your organization. See [User Access and JIT Provisioning](#user-access-and-jit-provisioning). | | Metadata URL | The URL that provides your IdP's SAML metadata, including the Entity ID, SSO login URL, and signing certificate. This URL allows LandingAI to automatically configure the SAML connection without requiring each value separately.
In Microsoft Entra ID, this is called **App Federation Metadata URL**. In Okta, this is called **Identity Provider Metadata**.
**Example**: `https://login.microsoftonline.com/123/federationmetadata/2007-06/federationmetadata.xml?appid=456` | | Enterprise email domains | Each email domain that will need access to Agentic Document Extraction.
**Example**: acme.com, acme.ai | | Email claim | The Uniform Resource Identifier (URI) for the email claim type. This communicates the email address of the user.
**Example**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | | Name claim | Optional. The Uniform Resource Identifier (URI) for the name claim type. This communicates the name of the user.
**Example**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | ### Required Information for OIDC Share the following information with the LandingAI team. Most of it can be found in your IdP's OIDC configuration page. The examples below are for Microsoft Entra ID. Formats and field names vary by IdP. | Item | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | IdP (Identity Provider) | The service provider your organization uses to manage email and SSO.
**Example**: Okta, Microsoft Entra ID, etc. | | JIT provisioning preference | Whether you want to enable Just-in-Time (JIT) provisioning for your organization. See [User Access and JIT Provisioning](#user-access-and-jit-provisioning). | | Client ID | A unique identifier for the Agentic Document Extraction application registered in your IdP. Your IdP generates this when you create the application. | | Client Secret | A secret key used to authenticate the Agentic Document Extraction application with your IdP. Share this with the LandingAI team through a secure channel. | | Issuer URL | The base URL of your IdP's OIDC configuration, used to locate the OIDC metadata endpoint.
**Example**: `https://login.microsoftonline.com/{tenant-id}/v2.0` | | Scope | The permissions requested from your IdP. At minimum: `openid`, `profile`, `email`. | | Enterprise email domains | Each email domain that will need access to Agentic Document Extraction.
**Example**: acme.com, acme.ai | ### Complete Setup in Your IdP After the LandingAI team enters your information in the Agentic Document Extraction backend, they will continue coordinating with you to complete the setup. The LandingAI team will give you the following information to enter in your IdP configuration page: | Protocol | Item | Description | | -------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | SAML 2.0 | Assertion Consumer Service URL | In Microsoft Entra ID, this is called a "Reply URL".
**Example**: `https://login.landing.ai/api/authn/...` | | SAML 2.0 | Audience URI | Also called an "SP Entity ID".
**Example**: `https://login.landing.ai/api/enterprise-sso/...` | | OIDC | Redirect URI (Callback URL) | **Example**: `https://login.landing.ai/callback/1234` | ### Test That SSO Is Working Correctly After adding the information from the LandingAI team, test that SSO is working correctly: 1. Go to [https://login.landing.ai/sign-in](https://login.landing.ai/sign-in). 2. If you are currently logged in, log out. 3. Click **Continue with Enterprise SSO** and follow the on-screen prompts to log in. If you're unable to log in, send an email to [support@landing.ai](mailto:support@landing.ai). ## View Your SSO Settings After SSO has successfully been configured, you can view your SSO settings in read-only mode in Agentic Document Extraction: 1. Log in to [https://ade.landing.ai/](https://ade.landing.ai/). 2. Go to the [Organization Settings](https://ade.landing.ai/settings/organization/general) page (to navigate there manually, click your profile icon at the bottom left corner of the page and click **Organization Settings**). 3. In the **Single Sign-On (SSO)** box, click **View Details**. The SSO settings display. # Plans & Billing Source: https://docs.landing.ai/ade/ade-pricing Understand ADE plan pricing, how costs are calculated, and how to manage overages and plan changes. This page covers what the Agentic Document Extraction plans cost and how billing works. To see how many credits each API call consumes, go to [Credit Consumption for ADE Gen2](/dpt3/credit-consumption) or [Credit Consumption for ADE Gen1](/ade/ade-credit-consumption). To see what your organization has already consumed, go to [Monitor Credit Usage](./monitor-usage). ## Pricing Agentic Document Extraction uses credit-based pricing. On the Explore and Team plans, a credit costs \$0.01 (\$1 buys 100 credits). Enterprise plans have custom pricing; for details, [contact us](mailto:support@landing.ai). All users start on our pay-as-you-go **Explore** plan with free credits. After that, you can stay on the Explore plan and buy credits as needed, or upgrade to a **Team** or **Enterprise** plan. See the full plan details and upgrade in the [app](https://ade.landing.ai/plan).
| Explore | Team | Enterprise | |
|---|---|---|---|
| Cost | Pay-as-you-go Start with 1000 free credits |
Credit packs start at \$250/mo | Contact us |
| Core Capabilities | |||
| Parsing [view supported file formats](./ade-file-types) |
|||
| Intelligent Layout | |||
| Structured Field Extraction | |||
| List Extraction | |||
| Table Extraction | |||
| Figure Summaries | |||
| Visual Grounding | |||
| Document Splitting | |||
| Multilingual Documents | |||
| Custom Processing Pipeline | |||
| Organization Management & Support | |||
| Users | 1 | Unlimited users | Unlimited users |
| Support Level | Community | Enhanced | Dedicated |
| Security & Deployment | |||
| Rate Limits [see more details](./ade-rate-limits) |
Base | Enhanced | Custom |
| Zero Data Retention (ZDR) | |||
| HIPAA (BAA) (inc. ZDR) | |||
| VPC and On-Prem Deployments | |||
| SLA & Uptime Guarantees | |||
| Single Sign-On (SSO) [see more details](./ade-sso) |
| Credit Type | Expiration |
|---|---|
| Free credits included in the Explore plan | Expire 90 days after you create your account |
| "Pay-As-You-Go" Credits Purchased (includes credits purchased via Auto Recharge) | Expire 1 year from the purchase date |
| Credits allocated as part of a subscription or Enterprise plan | Credits are allocated at the start of each billing cycle (for subscription plans) or subscription term (for Enterprise plans). Unused credits expire at the end of that period. |
6. To update your billing address, click **Manage**. This opens your billing information in Stripe.
7. Click **Update Information**. Update your billing information and click **Save**.
## Credit Alert Availability
Credit usage alerts are available on the **Team** and **Enterprise** plans.
Members with the **Developer** or **Admin** [role](./ade-members#member-roles) can view alerts on the [Usage page](https://ade.landing.ai/settings/usage). Only **Admins** can create, edit, and delete alerts.
## Credit Alert Workflow
Alerts work like this:
* Each alert has a threshold, a list of recipients, and an optional label.
* Your organization's consumption for the current billing period is checked against each alert's threshold every hour.
* When consumption crosses the threshold, the recipients receive an email. Each alert emails at most once per billing period, then starts watching again when the next period begins.
## Default Alerts
By default, organizations on the **Team** and **Enterprise** plans have three alerts that are sent to members with the **Admin** role. Default alerts can be deleted.
| Threshold | Label |
| ------------- | -------------- |
| 80% of quota | Usage warning |
| 90% of quota | Critical usage |
| 100% of quota | Quota reached |
## Create an Alert
Members with the **Admin** role can create alerts. To create an alert:
1. Go to the [Usage page](https://ade.landing.ai/settings/usage) and scroll down to the **Alert** section.
2. Click **Create Alert**.
3. Enter the **Alert threshold**: a number and its [unit](#alert-threshold-units) (**Credits**, **USD**, or **% of quota**).
4. Add up to 20 **Recipients**. Recipients must be members of your organization. A recipient who later leaves the organization stops receiving emails.
5. To describe the alert, add an optional **Label** (for example, "Finance overage warning").
6. Click **Create alert**.
## Edit or Delete an Alert
Members with the **Admin** role can edit and delete alerts. To change or remove an alert, open it from the alert table on the Usage page, then update its values or click **Delete Alert**.
## Alert Threshold Units
All three threshold units measure the same quantity: the credits your organization consumes in a billing period. The create dialog shows your subscription quota and the next reset date, and previews the equivalent credit value as you type.
| Unit | Description |
| ---------- | --------------------------------------------------------------- |
| Credits | The threshold as a number of credits. |
| USD | Converted to credits at the standard rate (\$1 = 100 credits). |
| % of quota | A percentage of your subscription quota for the billing period. |
## Alert Status
The alert table on the Usage page shows one of two statuses for each alert. Statuses reset automatically when a new billing period starts.
| Status | Meaning |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Watching | The alert has not fired during the current billing period. |
| Triggered | The alert fired during the current billing period. Recipients received the email, and the alert does not fire again until the next period. |
# Auto Recharge
Source: https://docs.landing.ai/ade/auto-recharge
Automatically buy credits when your balance falls below a threshold, so API calls don't fail when credits run out.
Use Auto Recharge to automatically purchase credits when your balance falls below a set threshold. If your organization runs out of credits, API calls fail with a `402` (Payment Required) status until you add more; Auto Recharge keeps a working balance so that doesn't happen.
Auto Recharge is available on the **Explore** and **Team** plans. It is enabled by default on **Team** plans and disabled by default on the **Explore** plan. To get an email about consumption instead of purchasing automatically, set a [credit usage alert](./credit-alerts).
## Set the Right Threshold
Set your threshold high enough to cover your largest expected API call. If your threshold is too low, Auto Recharge may not trigger before your balance is exhausted, and the API call will return a `402` status (Payment Required).
For example, if a typical job consumes 1,500 credits, set your threshold above 1,500 credits.
## Manage Auto Recharge
1. Log in to [https://ade.landing.ai](https://ade.landing.ai).
2. Go to the **Plan & Billing** page (to navigate there manually, click your profile icon at the bottom left corner of the page and click **Plan & Billing**).
3. If you're not currently in the correct organization, select your organization from the drop-down menu.
4. Click the **Plan** tab.
5. Click **Add Credits**. (If you're on the **Explore** plan, click **Buy Credits**.)
6. If Auto Recharge is not already enabled, turn on **Enable Auto Recharge**.
7. In the **When credit balance goes below** field, enter the threshold that will trigger Auto Recharge.
For example, entering 5,000 means credits are purchased automatically when your balance reaches 5,000 or fewer.
By default, this is 10% of the credits allocated for your billing cycle.
8. In the **Add to** field, enter the number of credits you want to purchase.
By default, this is 100% of the credits allocated for your billing cycle.
9. Click **Next** and follow the on-screen prompts.
# ADE Parse
Source: https://docs.landing.ai/api-reference/parse/ade-parse
Parse a document and return the parse response inline.
## OpenAPI
````yaml /dpt3/openapi-adev2.json post /v2/parse
openapi: 3.1.0
info:
title: >-
LandingAI Agentic Document Extraction (ADE) Gen2 API: Parse, Extract, and
Ground Documents with DPT-3
description: >-
Parse and extract data from documents with DPT-3, a document parsing model
from LandingAI, using the Agentic Document Extraction (ADE) v2 endpoints.
Parse converts PDFs and images into structured Markdown and elements with
per-element grounding (page numbers and coordinates) for RAG, search, and
extraction pipelines. Extract pulls specific fields from parsed Markdown
using a JSON schema. Ground maps extracted fields back to the source blocks,
with page numbers and bounding boxes for each value. Documentation:
https://docs.landing.ai
version: 1.0.0
servers:
- url: https://api.ade.landing.ai
description: Production API
security: []
paths:
/v2/parse:
post:
tags:
- Parse
summary: ADE Parse
description: Parse a document and return the parse response inline.
operationId: parse_run_sync
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
document:
type: string
format: binary
description: >-
The file to parse. The file must be a PDF or image; see the
list of [supported file
types](https://docs.landing.ai/dpt3/file-types). Provide
either `document` or `document_url`, not both.
document_url:
type: string
description: >-
A publicly accessible URL to the file to parse. The file
must be a PDF or image; see the list of [supported file
types](https://docs.landing.ai/dpt3/file-types). Provide
either `document` or `document_url`, not both.
model:
type: string
description: >-
The DPT-3 model snapshot to use for this request. Accepts a
dated snapshot (for example, `dpt-3-pro-20260710`), a
`-latest` alias, or a bare family name (equivalent to that
family's `-latest`). Two families are available: `dpt-3-pro`
for highest quality, and `dpt-3-verity` for lower-latency
parsing without vision-model captioning. Defaults to the
latest DPT-3 Pro snapshot.
options:
additionalProperties: false
properties:
pages:
anyOf:
- items:
type: integer
type: array
- type: 'null'
default: null
title: Pages
blocks:
$ref: '#/components/schemas/BlocksOptions'
atomic_grounding:
default: true
description: >-
Include the fine-grained `atomic_grounding` array on
leaf elements. Set `false` to omit the field entirely
from every node.
title: Atomic Grounding
type: boolean
inline_markdown:
default: false
description: >-
Include each node's slice of the document `markdown`
inline as a `markdown` field on every structure node:
the document root, each page, and each element
(including table cells). `atomic_grounding` entries do
not carry it.
title: Inline Markdown
type: boolean
password:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Password for encrypted PDFs. Not currently supported —
providing a value returns a 422 error; decrypt the file
before uploading.
title: Password
title: ParseOptions
type: object
description: >-
Optional object that customizes the parse. Use it to select
which pages to process, adjust how content appears in the
Markdown, or control how much detail the response includes.
Sent as a JSON-serialized string in form data.
responses:
'200':
description: The parse response
content:
application/json:
schema:
$ref: '#/components/schemas/ParseResponse'
'206':
description: Partial success (some pages failed to parse)
content:
application/json:
schema:
$ref: '#/components/schemas/ParseResponse'
'422':
description: Request validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl -X POST 'https://api.ade.landing.ai/v2/parse' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'document=@document.pdf' \
-F 'model=dpt-3-pro-latest'
- lang: Python
label: Python
source: >-
import requests
url = 'https://api.ade.landing.ai/v2/parse'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
files = {'document': open('document.pdf', 'rb')}
data = {'model': 'dpt-3-pro-latest'}
response = requests.post(url, headers=headers, files=files,
data=data)
print(response.json())
- lang: JavaScript
label: Node.js
source: |-
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('document', fs.createReadStream('document.pdf'));
form.append('model', 'dpt-3-pro-latest');
axios.post('https://api.ade.landing.ai/v2/parse', form, {
headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...form.getHeaders() }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
components:
schemas:
BlocksOptions:
additionalProperties: false
properties:
text:
$ref: '#/components/schemas/BaseElementOptions'
table:
$ref: '#/components/schemas/TableOptions'
figure:
$ref: '#/components/schemas/FigureOptions'
marginalia:
$ref: '#/components/schemas/BaseElementOptions'
attestation:
$ref: '#/components/schemas/BaseElementOptions'
logo:
$ref: '#/components/schemas/BaseElementOptions'
scan_code:
$ref: '#/components/schemas/BaseElementOptions'
card:
$ref: '#/components/schemas/BaseElementOptions'
title: BlocksOptions
type: object
ParseResponse:
description: |-
The parse result: the full document as `markdown`, its hierarchical
`structure` (with per-node spatial `grounding` inline), and request
`metadata`.
properties:
markdown:
description: The full document as a single Markdown string, in reading order.
title: Markdown
type: string
metadata:
$ref: '#/components/schemas/ParseMetadata'
description: >-
Information about the request: model version, page count, duration,
billing, and more.
structure:
$ref: '#/components/schemas/Document'
description: >-
The document's hierarchical structure: pages and the elements
detected on each page. Every node below the root carries its spatial
data inline in a `grounding` object (`{page, range, box}`,
normalized page coordinates); leaf elements additionally carry
`atomic_grounding`.
required:
- markdown
- metadata
- structure
title: ParseResponse
type: object
ErrorResponse:
type: object
title: ErrorResponse
required:
- code
- message
properties:
code:
type: string
description: >-
Stable snake_case error code (e.g. ``validation_error``,
``unknown_model_version``, ``invalid_url``, ``invalid_api_key``,
``rate_limit_exceeded``).
message:
type: string
description: Human-readable detail.
BaseElementOptions:
additionalProperties: false
properties:
markdown:
default: true
title: Markdown
type: boolean
title: BaseElementOptions
type: object
TableOptions:
additionalProperties: false
properties:
markdown:
default: true
title: Markdown
type: boolean
format:
default: html
enum:
- markdown
- html
title: Format
type: string
title: TableOptions
type: object
FigureOptions:
additionalProperties: false
properties:
markdown:
default: true
title: Markdown
type: boolean
title: FigureOptions
type: object
ParseMetadata:
description: Information about a parse request.
properties:
job_id:
anyOf:
- type: string
- type: 'null'
description: >-
The parse job identifier — always server-minted and unique per
submit. On the async `/jobs` route this is the id the caller polls.
Correlates with the job's entry in your billing dashboard. Format:
``
## Common Tasks
Each command below takes a job item ID, or any unambiguous prefix of one. AI agents: `ade help --json` returns this whole surface as one JSON object.
| To do this | Run | Learn more |
| ---------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
| Parse a local file at half the credits | `ade parse -d document.pdf --tier standard` | [Parse Documents](./parse) |
| Parse in the fast lane, at the full rate | `ade parse -d document.pdf --tier priority` | [Parse Documents](./parse) |
| Parse only some pages | `ade parse -d document.pdf --pages 1,3-5` | [Parse Documents](./parse) |
| Extract fields from a parse | `ade extract JOB_ID --schema schema.json` | [Extract Fields](./extract) |
| Get the result as JSON for a script | `ade extract JOB_ID --schema schema.json --json` | [Scripting and Automation](./scripting-automation) |
| See your past runs | `ade history list` | [CLI Concepts](./concepts) |
| Search a parsed document | `ade find JOB_ID "term"` | [Find, Crop, and View](./find-crop-view) |
| Open a document in the viewer | `ade view JOB_ID --open` | [Find, Crop, and View](./find-crop-view) |
| Save an element as an image | `ade crop JOB_ID --element-id ID` | [Find, Crop, and View](./find-crop-view) |
| Capture an ID for a script | `ade parse -d document.pdf --id-only` | [Scripting and Automation](./scripting-automation) |
| Check which account you are using | `ade auth status` | [Authentication](./authentication) |
# Authentication
Source: https://docs.landing.ai/cli/authentication
Log in with your browser or an API key, choose which organization your runs use, and target the US or EU.
Log in once per machine and the ade CLI remembers you. Pick the path that fits where you are:
* At a terminal with a browser, run `ade login`. This is the simplest path.
* Without a browser, log in with an API key.
* Without a terminal, such as a continuous integration (CI) pipeline or an AI agent, set the `ADE_API_KEY` environment variable.
## Log In with Your Browser
Run `ade login` to open your browser and authenticate with your [ADE account](https://ade.landing.ai/). The ade CLI stores the credential and refreshes it as needed. If it reports that the session is unusable, run `ade login` again.
```bash theme={null}
ade login
```
If you belong to more than one organization, the CLI asks which one to use, and runs consume credits from the organization you choose. If you belong to only one, the CLI selects it for you. To choose without answering a prompt, name the organization with `--org`.
```bash theme={null}
ade login --org "Acme Research"
```
## Log In with an API Key
Use an API key when you have no browser to log in with. A key always acts in the organization it was created in, so there is nothing to choose. Create a key in your [account settings](https://ade.landing.ai/settings/api-key).
Then log in. The CLI prompts you for the key, and shows no characters as you type or paste it.
```bash theme={null}
ade auth login --api-key -
```
## Run Without a Terminal
In CI, cron, or an AI agent harness, authenticate with an API key. Two ways work, and they differ in whether the key is stored on the machine:
* Set the `ADE_API_KEY` environment variable. The key is never written to disk, and it overrides any stored credential. Use this unless you need the key to persist.
* Pipe the key into login. The CLI stores it, exactly as the prompt would.
```bash theme={null}
echo "$YOUR_KEY" | ade auth login # stored
```
## View and Change Organizations
These commands apply to browser logins. To see the organizations you belong to and which one is selected, list them. The list is read live, so a change to your access shows up immediately.
```bash theme={null}
ade auth org list
```
To point later runs at a different organization, switch to it by ID or name. Switching needs no browser and no new login. Clearing the selection falls back to your account's default organization.
```bash theme={null}
ade auth org switch "Acme Research"
ade auth org clear
```
## Work Across Environments
There is no "current environment" to switch. Every command resolves its target fresh: the `--env` flag if given, else the `ADE_ENV` variable, else `production`. To make one shell sticky, export the variable there (`export ADE_ENV=eu`) while other shells keep working against production.
API keys are region-specific, so a US key does not work in the EU. The CLI stores credentials per environment for the same reason, and job items are per-environment too: a parse run in the EU never serves a production request. For more about using ADE in the EU, see [European Union (EU)](/dpt3/eu).
| Environment | Endpoint |
| ---------------------- | -------------------------------------- |
| `production` (default) | `https://api.ade.landing.ai` |
| `eu` | `https://api.ade.eu-west-1.landing.ai` |
## Check Your Authentication Status
To see which environment you are targeting, which organization a browser login acts in, and where else you hold credentials:
```bash theme={null}
ade auth status
```
## Log Out
By default, logging out clears the credential for the environment you are targeting. Add `--env` to name a different one, or `--all` to clear every environment at once.
```bash theme={null}
ade auth logout
```
# CLI Concepts
Source: https://docs.landing.ai/cli/concepts
Understand job items, free re-runs, resumable jobs, and the local store the ade CLI serves results from.
The ade CLI saves every parse and extract run on your machine and serves later reads from that store. Because the results are already on disk:
* Re-running an identical command consumes no credits, because the CLI serves it from disk.
* An interrupted job resumes instead of restarting.
* Every result stays available to search, cite, and reuse.
If you haven't run a command yet, the [Quickstart](./quickstart) gets you there in minutes.
## Every Run Is a Job Item
Every command that sends work to the ADE API, such as `ade parse` or `ade extract`, is recorded as a **job item**: the run itself plus everything it produced, in its own folder on your machine. Each job item has a 16-character ID, and every command that reads the store accepts the ID or any unambiguous prefix of it.
A job item's identity is what defines the run: the command, its parameters, the environment, and the document's path and contents. Change any of those, by editing the document, moving it, or passing different parameters, and the next run creates a new job item rather than replacing the old one.
To see your job items, newest first, list your history:
```bash Command theme={null}
ade history list
```
```text Output theme={null}
d6b53a431d653464 parse parsed production 2026-08-31 15:12 dpt-3-pro-latest · standard ~/documents/kyc-form.pdf
```
## Commands Are Guarantees
A **guarantee command** ensures a state instead of firing a request: running `ade parse` means "make sure this exact run exists." If it already exists, the CLI serves the result from disk with an explicit notice, makes no API call, and consumes no credits.
```bash Command theme={null}
ade parse -d kyc-form.pdf --tier standard
```
```text Output theme={null}
already parsed — job item d6b53a431d653464 (completed 2026-08-31 22:12 UTC); pass --force to re-parse
source: /Users/you/documents/kyc-form.pdf
run: parse-01m1cy2vs6bep5k9a7naz30jfc
model: dpt-3-pro-20260710
pages: 1 (0 failed)
credits: 1.4 (standard)
saved: ~/.ade/jobs/d6b53a431d653464/ (parse.json, parse.md, elements.json)
next: ade view d6b53a43 --open · ade extract d6b53a43 --schema | LEGAL FIRST NAME | MIDDLE NAME / INITIAL | LEGAL LAST NAME |
| Margaret | L. | Okonkwo |
| DATE OF BIRTH | COUNTRY OF CITIZENSHIP | TAX IDENTIFICATION NO. (SSN/EIN) |
| 09 / 14 / 1978 | United States | ***-**-7291 |
## Billing Metadata for Jobs That Save Output to a URL
[Parse Jobs](./parse-async) and [Extract Jobs](./extract-async) created with `output_save_url` now report the job's `metadata` (including `billing`) in the completed poll response, and the file delivered to your URL contains the complete response, also including `metadata`.
This also applies to jobs that completed before this change: poll the job again, and the response now includes its `metadata`.
## Smoother Job Progress Reporting
The `progress` field on [Parse Jobs](./parse-async) and [Extract Jobs](./extract-async) polls now updates on every poll as an estimate of how close the job is to completion, instead of staying at `0` for most of a run.
## Playground Updates
* Search the parse results with the toolbar's find-in-page search, fold JSON objects, and toggle word wrap. See [Review the Results](./playground#review-the-results).
* The parse toolbar is redesigned, and the Config menu's grounding control is now named **Atomic grounding** (previously "Fine-grained output"). See [Customize the Parse Output with Config](./playground#customize-the-parse-output-with-config).
* Hovering a block in the Parse tab reveals its per-line and per-cell boxes on the document, and hovering an extracted field in the Extract tab highlights and labels where its value appears in the document.
Identifies elements like text, tables, and form fields with exact page and coordinate references. | Use to convert documents into structured data for downstream applications, such as RAG, search, and training LLMs.
This is the required first step for all ADE workflows. | | [Extract](./ade-extract) | Pulls specific data fields from parsed documents using schema-based extraction. | Use when you need the values for specific fields.
Can be used after Parse or Split. | | [Classify](./ade-classify) | Assigns a category to each page of a document based on classes you define. | Use when you need to sort, route, or label pages by document type. Does not require Parse. | | [Section](./ade-section) | Analyzes a parsed document and generates a hierarchical table of contents with section titles, levels, and chunk references. | Use when you need to navigate, scope, or retrieve content by section (for example, for section-aware RAG chunking or document review tools). | | [Split](./ade-split) | Classifies and separates parsed documents into multiple sub-documents based on document types you define. | Use when one file contains multiple documents that need to be separated, such as batched Know Your Customer (KYC) documents. | ## Get Started
}
href="./ade-typescript"
>
Use our TypeScript library to build custom scripts.
3. If you're on a subscription plan, you can [create an API key](#create-api-keys-subscription-plans-only) if needed.
4. Click the **Copy** icon to copy your API key.
## Personal Plans (Explore Plans) Have One API Key
The personal plan (the "Explore" plan) only has one API key. This API key cannot be deleted or revoked.
The Explore plan type is designed for testing, prototyping, and hobby use. If you'd like to deploy to production and need more granular API key management, like the ability to create and revoke API keys, [upgrade](./ade-pricing) to a subscription plan.
3. If you're not currently in the correct organization, select your organization from the drop-down menu.
4. Click **Create Key**.
5. Enter a brief, descriptive name for the API key in the key name field.
6. Click **Create API Key**.
7. Click the **Copy** icon to copy the API key.
8. Click **Done** to close the pop-up.
## Revoke API Keys
If you are on the Team or Enterprise plan, you can revoke API keys. A user with the Admin role can revoke any API key. A user with the Developer role can revoke only API keys they have created.
To revoke an API key:
1. Log in to [https://ade.landing.ai/](https://ade.landing.ai/).
2. Go to the [API Key](https://ade.landing.ai/settings/api-key) page (to navigate there manually, click your profile icon at the bottom left corner of the page and click **API Key**).
3. If you're not currently in the correct organization, select your organization from the drop-down menu.
4. Locate the row for the API key. (You may need to search to narrow down the list of API keys.)
5. Click the **Settings** button (ellipses) and select **Revoke API Key**. Follow the on-screen prompts to complete the process.
## Set Your API Key When Using the Library
The client libraries read your API key from the `VISION_AGENT_API_KEY` environment variable. [Get your API key](#get-your-api-key) first, then set it using any of the methods below. Do not hard-code your API key in source files.
The examples below use the [ade-python library](./ade-python); the [TypeScript library](./ade-typescript) reads the same environment variable.
### Method 1: Set the API Key as an Environment Variable
1. Set the environment variable. To persist the key across sessions on macOS or Linux, add the `export` command to your shell profile (`.zshrc` or `.bashrc`), then run `source ~/.zshrc`.
## From Playground to Production
If you're new to Agentic Document Extraction, start with the [Playground](https://ade.landing.ai/) rather than jumping straight into the APIs. The Playground gives you an immediate, visual way to explore what [Parse](./parse), [Extract](./ade-extract), [Classify](./ade-classify), [Section](./ade-section), and [Split](./ade-split) can do with your specific documents.
Use the Playground to:
* **Test your use case before writing any code.** Upload your actual documents and see how Agentic Document Extraction handles them. Can it parse faxed medical records? Extract supplier IDs consistently across invoices from different vendors? Handle long financial tables in earnings reports? You'll get immediate answers.
* **Build extraction and split schemas visually.** The schema wizard guides you through creating, editing, and validating schemas using a point-and-click interface.
* **Export production-ready code.** Once you're satisfied with the results, the Playground generates the API or library code you need to replicate the same processing programmatically.
When you're ready to scale, use the [API](https://docs.landing.ai/api-reference/tools/ade-parse) or the [Python](./ade-python) or [TypeScript](./ade-typescript) libraries. The Playground is not intended for production use and has limitations such as lower rate limits.
## Files Are Organized into Projects
Files in the Playground are organized into **projects**. Projects let you group similar documents together. You can then [create and apply extraction schemas](./ade-extract-playground) across multiple documents at once.
To view all files you've uploaded to the Playground, click **Projects** in the left navigation bar.
## Chat with Document
After the Playground parses a file, you can use the **Chat with Document** tool to interact with the document.
The Chat with Document tool is an LLM layered on top of the output of the ADE Parse API. The chat tool showcases how the API accurately parses and understands document data, including element locations. Use the chat tool to get inspired for how you can build custom solutions on top of the API.
The Chat with Document tool suggests a few prompts based on your document. You can also enter your own prompts.
Like the Playground itself, the Chat with Document tool is an example of what you can build, and is not part of the Agentic Document Extraction API.
## Manage Your Account in the Playground
The Playground is also used to create and manage your account. For more information, go to [Organizations & Members](./ade-members).
# Python Library
Source: https://docs.landing.ai/ade/ade-python
Process documents using the ADE Python library.
The [ade-python](https://github.com/landing-ai/ade-python) library is a lightweight Python library you can use for parsing documents, classifying pages, extracting data, generating tables of contents, and splitting documents into sub-documents.
The library is automatically generated from our API specification, ensuring you have access to the latest endpoints and parameters.
## Install the Library
```bash theme={null}
pip install landingai-ade
```
## Set the API Key as an Environment Variable
To use the library, first [generate an API key](https://ade.landing.ai/my/settings/api-key). Save the key to a `.zshrc` file or another secure location on your computer. Then export the key as an environment variable.
```bash theme={null}
```
| Description | Amount |
|---|---|
| Strategic planning consultation (40 hours @ $150/hr) | $6,000.00 |
| Market analysis report preparation | $3,500.00 |
| Implementation roadmap development | $2,250.00 |
| Executive presentation materials | $1,500.00 |
| Follow-up consultation sessions (15 hours @ $150/hr) | $2,250.00 |
| Travel expenses (reimbursable) | $250.00 |
| TOTAL | $15,750.00 |
| Description | Amount |
|---|---|
| Strategic planning consultation (40 hours @ $150/hr) | $6,000.00 |
| Market analysis report preparation | $3,500.00 |
| Implementation roadmap development | $2,250.00 |
| Executive presentation materials | $1,500.00 |
| Follow-up consultation sessions (15 hours @ $150/hr) | $2,250.00 |
| Travel expenses (reimbursable) | $250.00 |
| TOTAL | $15,750.00 |
| Description | Amount |
|---|---|
| Strategic planning consultation (40 hours @ $150/hr) | $6,000.00 |
| Market analysis report preparation | $3,500.00 |
| Implementation roadmap development | $2,250.00 |
| Executive presentation materials | $1,500.00 |
| Follow-up consultation sessions (15 hours @ $150/hr) | $2,250.00 |
| Travel expenses (reimbursable) | $250.00 |
| TOTAL | $15,750.00 |
}
href="./ade-typescript#parse-getting-started"
>
Run Parse with our TypeScript library.
}
href="https://docs.landing.ai/ade/ade-typescript#parse-jobs"
>
Run Parse Jobs with our TypeScript library.
## Use Custom Prompts with the API
Here is the rendered Markdown for that chunk:
### Example: Lists
Here is an example of the API marking a list as a `text` chunk:
Here is the rendered Markdown for that chunk:
## Table
A `table` chunk type is a grid of rows and columns containing data.
Agentic Document Extraction doesn't require gridlines to be present, and typically interprets well-aligned sets of data to be part of a table. For example, part of a receipt can be extracted as a table if the purchased items align with the costs.
When you parse spreadsheets, sets of data are also interpreted as `table` chunks.
### Example: Receipt
Here is an example of the API marking receipt line items as a `table` chunk:
Here is the rendered Markdown for that chunk:
### Example: Earnings Statement
Here is an example of the API marking part of an earnings statement as a `table` chunk:
Here is the rendered Markdown for that chunk:
### Example: Spreadsheet
Here is an example of the API marking data in a spreadsheet as a `table` chunk:
Here is the rendered Markdown for that chunk:
## Marginalia
A `marginalia` chunk type is a set of text in the top, bottom, or side margins of a document, including:
* page headers
* page footers
* page numbers
* handwritten notes in margins
* line numbers on one side of a page
#### Example: Header and Page Number
Here is an example of the API marking a header and page number as a `page_header` chunk:
Here is the rendered Markdown for that chunk:
## Figure
A `figure` chunk type is an element that contains visual or graphical non-text content, including:
* pictures
* graphs (bar graphs, line graphs, etc.)
* flowcharts
* diagrams
### Example: Medical Imaging
Here is an example of the API marking a pathology image as a `figure` chunk:
Here is the rendered Markdown for that chunk:
### Example: Bar Chart
Here is an example of the API marking a bar chart as a `figure` chunk:
Here is the rendered Markdown for that chunk:
## Logo
A `logo` chunk type identifies logos.
Here is the rendered Markdown for that chunk:
## Card
A `card` chunk type identifies:
* ID cards
* driver licenses
Here is the rendered Markdown for that chunk:
## Attestation
An `attestation` chunk type includes:
* signatures
* stamps
* seals
Here is the rendered Markdown for that chunk:
## Scan\_code
A `scan_code` chunk type identifies:
* QR codes
* bar codes
Here is the rendered Markdown for these chunks:
# JSON Response for Parsing
Source: https://docs.landing.ai/ade/ade-json-response
Understand the parse JSON response: markdown, chunks, splits, grounding, and metadata fields.
When you parse a document with the [ADE Parse API](https://docs.landing.ai/api-reference/tools/ade-parse) or complete an [ADE Parse Job](https://docs.landing.ai/api-reference/tools/ade-parse-jobs), the parsed data is returned in a structured JSON format.
The fields and structure of API responses are detailed in the [API Reference](https://docs.landing.ai/api-reference/tools/ade-parse). This article is designed to give additional context about the returned fields and how to use them.
## Response Structure
The response contains the following top-level fields:
| Field | Description |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`markdown`](./ade-markdown-response) | Complete Markdown representation of the document. |
| [`chunks`](#parsed-chunks-chunks) | Array of `chunk` objects, one for each parsed region. |
| [`splits`](#splits) | Array of `split` objects organizing chunks by page or section. |
| [`grounding`](#grounding-information-grounding) | Object mapping chunk IDs to detailed grounding information, which includes the page number and bounding box coordinates. |
| `metadata` | Processing information (credit usage, duration, filename, job ID, page count, version). For partial content responses, includes a `failed_pages` array listing page numbers that failed to process. |
## Chunk, Table, and Cell Identifiers
Each chunk, table, and table cell has a unique identifier (ID) that appears in multiple parts of the API response. Use these IDs to link different sets of information across the response.
The ID format depends on the element type:
| ID Type | Format | Example |
| -------------- | ------------------------------------------ | -------------------------------------- |
| Chunk IDs | UUID format | `7d58c5cf-e4f5-4a7e-ba34-0cd7bc6a6506` |
| Table IDs | `{page_number}-{base62_sequential_number}` | `0-1` |
| Table cell IDs | `{page_number}-{base62_sequential_number}` | `0-2`, `0-3` |
### Sequential Numbering for Tables and Cells
Table and cell IDs use sequential numbering within each page. The first table element on the first page has ID `0-1`, and its first cell has ID `0-2`. All subsequent table elements and cells on that page continue this sequential numbering (`0-3`, `0-4`, etc.).
The numbering restarts for each new page. For example, the first table on the second page will have ID `1-1`, and its first cell will have ID `1-2`.
## Parsed Chunks (`chunks`)
A [chunk](./ade-chunk-types) is a distinct region or element in the parsed document. The `chunks` array contains all parsed chunks from the document in reading order.
Each `chunk` object in the `chunks` array contains:
| Field | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Chunk [unique identifier](#chunk-table-and-cell-identifiers) (UUID format). |
| `markdown` | [Markdown](./ade-markdown-response) content for the chunk. |
| `type` | [Chunk type](./ade-chunk-types). |
| `grounding` | The location of the chunk in the document. Contains page number and [bounding box coordinates](#working-with-bounding-box-coordinates). |
## Splits
- `full`: Used when the `split` parameter was not included, and the array includes one entry for the entire document.
- `page`: Used when the `split` parameter was included, and the array contains an entry for each page.
- `full`: Used when the `split` parameter was not included, and the array includes one entry for the entire document.
- `page_{number}`: Used when the `split` parameter was included. Includes the zero-indexed page number. Examples: `page_0`, `page_1`
The parsed response is shown below, with key elements highlighted in the table:
| Line | Description | ID |
| ------- | --------------------------------------------------------- | ------------------------------------ |
| Line 47 | `grounding` object begins | N/A |
| Line 48 | Grounding for the text "Bank Account Rates" | 2831e56d-94f5-4ec4-b001-6e16e188119b |
| Line 58 | Grounding for the table chunk | 54905c88-b4b8-45a7-84b5-1dcf5f1d1e60 |
| Line 68 | Grounding for the table ID | 0-1 |
| Line 78 | Grounding for the first cell in the table, "Account Type" | 0-2 |
```json [expandable] lines highlight={47, 48, 58, 68, 78} theme={null}
{
"markdown": "\n\n## Bank Account Rates\n\n\n\n| Account Type | APY |
| Checking | 0.25% |
| Savings | 3.30% |
| Account Type | APY |
| Checking | 0.25% |
| Savings | 3.30% |
| Account Type | APY |
| Checking | 0.25% |
| Savings | 3.30% |
The `grounding` field from the response is shown below, with key elements highlighted in the table:
| Line | Description | ID |
| ------- | ---------------------------------------------------- | ------------------------------------ |
| Line 1 | `grounding` object | N/A |
| Line 2 | Grounding for the table chunk | ef24b1ea-8dac-4a24-bf60-704b7c6a6bca |
| Line 12 | Grounding for the table ID | 0-1 |
| Line 22 | Grounding for the first cell in the table, "Cell 1" | 0-2 |
| Line 39 | Grounding for the second cell in the table, "Cell 2" | 0-3 |
```json [expandable] lines highlight={1, 2, 12, 22, 39 } theme={null}
"grounding": {
"ef24b1ea-8dac-4a24-bf60-704b7c6a6bca": {
"box": {
"left": 0.15924638509750366,
"top": 0.19857195019721985,
"right": 0.6330658197402954,
"bottom": 0.313611775636673
},
"page": 0,
"type": "chunkTable"
},
"0-1": {
"box": {
"left": 0.16758577831817933,
"top": 0.20629539815303133,
"right": 0.6280869812016796,
"bottom": 0.3090690124206503
},
"page": 0,
"type": "table"
},
"0-2": {
"box": {
"left": 0.16758577831817933,
"top": 0.2062988834957917,
"right": 0.39743034595752635,
"bottom": 0.3090588206865543
},
"page": 0,
"type": "tableCell",
"position": {
"row": 0,
"col": 0,
"rowspan": 1,
"colspan": 1,
"chunk_id": "ef24b1ea-8dac-4a24-bf60-704b7c6a6bca"
}
},
"0-3": {
"box": {
"left": 0.3972880070815534,
"top": 0.20629539815303133,
"right": 0.6280869812016795,
"bottom": 0.3090690124206503
},
"page": 0,
"type": "tableCell",
"position": {
"row": 0,
"col": 1,
"rowspan": 1,
"colspan": 1,
"chunk_id": "ef24b1ea-8dac-4a24-bf60-704b7c6a6bca"
}
}
},
```
### Table Cell Position Information
Each table cell (`tableCell`) includes a `position` field that provides the cell's location in the table grid.
The `row` and `col` values are zero-indexed, where `row: 0, col: 0` represents the first row and first column of the table.
The `rowspan` and `colspan` values indicate merged cells, with a value of 1 meaning the cell is not merged in that direction.
| Field | Description |
| ---------- | ------------------------------------------- |
| `row` | Row position (integer, zero-indexed). |
| `col` | Column position (integer, zero-indexed). |
| `rowspan` | Number of rows the cell spans (integer). |
| `colspan` | Number of columns the cell spans (integer). |
| `chunk_id` | Associated chunk identifier (string). |
#### How to Use the Table Cell Positions
Use the table cell position information in the `grounding` to:
* Map parsed data back to specific cells in the original table (for example, verify that a dollar amount came from row 2, column 3)
* Identify merged cells through the `rowspan` and `colspan` values
* Programmatically reference cells by their row and column indices
### Confidence Score
Agentic Document Extraction returns confidence scores for text, marginalia, card, and table chunks, as well as table cells, when parsing with DPT-2.
Confidence scores measure the confidence level of parsed text in Markdown with respect to the actual text or visual data present in the document.
Each score ranges from 0.0 (low confidence) to 1.0 (high confidence). Lower values indicate regions where the model was less certain about the output.
For example, here are the confidence score fields for a chunk:
```json Confidence score fields highlight={11-12} theme={null}
"grounding": {
"42ca60d3-a606-4c9a-a61e-493966b63fd9": {
"box": {
"left": 0.8607578277587891,
"top": 0.9346558451652527,
"right": 0.9316827058792114,
"bottom": 0.951895534992218
},
"page": 0,
"type": "chunkMarginalia",
"confidence": 0.991,
"low_confidence_spans": []
}
}
```
#### Confidence Score Fields
The grounding object includes the following confidence-related fields:
| Field | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `confidence` | Overall confidence score for the chunk or element (0.0 to 1.0). When `low_confidence_spans` contains entries, this is the lowest of the span-level or cell-level confidence scores. |
| `low_confidence_spans` | Array of objects identifying specific text substrings with confidence scores of 0.95 or lower. Empty array if no low-confidence substrings exist. Learn more in [Low Confidence Spans](#low-confidence-spans). |
#### Low Confidence Spans
The `low_confidence_spans` array contains substrings that have confidence scores of 0.95 or lower.
Each object in the `low_confidence_spans` array contains:
| Field | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | The substring that has low confidence. |
| `span` | Two-element array `[start, end]` indicating the character position range of the substring within the chunk's text. Positions are zero-indexed. |
| `confidence` | Confidence score for this specific substring (0.0 to 1.0). |
For example, in the parse response below, the API has low confidence for two spans of text within the chunk.
```json Low confidence spans highlight={11-27} theme={null}
"grounding": {
"6be7d3cf-6664-42c7-906c-4957882e40ff": {
"box": {
"left": 0.24479518830776215,
"top": 0.9269143342971802,
"right": 0.6804859042167664,
"bottom": 0.9461647272109985
},
"page": 0,
"type": "chunkText",
"confidence": 0.25,
"low_confidence_spans": [
{
"text": " 1220",
"span": [
8,
13
],
"confidence": 0.25
},
{
"text": "15?\"",
"span": [
26,
30
],
"confidence": 0.62
}
]
}
}
```
#### Chunks and Elements with Confidence Scores
Confidence scores are available for text, marginalia, card, and table chunks, as well as table cells.
The `tableCell` elements have confidence scores but do not include `low_confidence_spans`
| Grounding Type | Chunk Type | Has Confidence Score | Has Low Confidence Spans |
|---|---|---|---|
chunkText |
text |
||
chunkMarginalia |
marginalia |
||
chunkCard |
card |
||
chunkTable |
table |
||
table |
— | — | — |
tableCell |
— | — | |
chunkFigure |
figure |
— | — |
chunkLogo |
logo |
— | — |
chunkAttestation |
attestation |
— | — |
chunkScanCode |
scan\_code |
— | — |
| Field | Description | Global Grounding Object | Chunk-Level Grounding |
|---|---|---|---|
box |
Bounding box coordinates | ||
page |
Zero-indexed page number | ||
confidence |
Confidence score | ||
low\_confidence\_spans |
Sections of text with low confidence scores, if any | ||
type |
Detailed element type | ||
position |
Table cell position |
| Feature | Specification |
| Battery Life | Up to 30 hours with ANC on |
| Connectivity | Bluetooth 5.3, USB-C |
| Driver Size | 40mm dynamic drivers |
| Weight | 250 grams |
| Charging Time | 2.5 hours (full charge) |
| Feature | Specification |
| Battery Life | Up to 30 hours with ANC on |
| Connectivity | Bluetooth 5.3, USB-C |
| Driver Size | 40mm dynamic drivers |
| Weight | 250 grams |
| Charging Time | 2.5 hours (full charge) |
| Feature | Specification |
| Battery Life | Up to 30 hours with ANC on |
| Connectivity | Bluetooth 5.3, USB-C |
| Driver Size | 40mm dynamic drivers |
| Weight | 250 grams |
| Charging Time | 2.5 hours (full charge) |
Below is the full parsing response for this document with the `markdown` fields highlighted. Notice that each chunk's HTML anchor tag (the `` element) appears consistently across all `markdown` fields.
This consistency means you can reference any chunk by its ID, whether you're working with the complete document Markdown, a specific split, or an individual chunk.
```json Markdown Fields {2,5,19,33,47,68} [expandable] theme={null}
{
"markdown": "\n\nSKU\nWH-2847-BLK\n\n\n\nQUANTITY\n\n48 Units\n\n\n\n<::scan_code: Barcode\n\nThis is a clear, well-defined linear barcode with distinct black bars on a white background, showing no visible quality issues.::>\n\n\n\n2847 0000 4812\n---\n",
"chunks": [
{
"markdown": "\n\nSKU\nWH-2847-BLK",
"type": "text",
"id": "69a645fe-8617-4be8-b66f-68d7788755c0",
"grounding": {
"box": {
"left": 0.06628379225730896,
"top": 0.09509064257144928,
"right": 0.4664609134197235,
"bottom": 0.2678269147872925
},
"page": 0
}
},
{
"markdown": "\n\nQUANTITY\n\n48 Units",
"type": "text",
"id": "bdaf2198-0fdc-4c94-be54-a49ca796ea0f",
"grounding": {
"box": {
"left": 0.06750398874282837,
"top": 0.3068091869354248,
"right": 0.3204823434352875,
"bottom": 0.47341251373291016
},
"page": 0
}
},
{
"markdown": "\n\n<::scan_code: Barcode\n\nThis is a clear, well-defined linear barcode with distinct black bars on a white background, showing no visible quality issues.::>",
"type": "scan_code",
"id": "65fe085e-b8c8-46e0-848c-f0c32ccf16e8",
"grounding": {
"box": {
"left": 0.11207544803619385,
"top": 0.5374823212623596,
"right": 0.8830909729003906,
"bottom": 0.8660760521888733
},
"page": 0
}
},
{
"markdown": "\n\n2847 0000 4812\n---\n",
"type": "text",
"id": "9e551c40-3eaa-4d77-a219-50b7f4a57e05",
"grounding": {
"box": {
"left": 0.28996485471725464,
"top": 0.9088556170463562,
"right": 0.7057502269744873,
"bottom": 0.9888754487037659
},
"page": 0
}
}
],
"splits": [
{
"class": "page",
"identifier": "page_0",
"pages": [
0
],
"markdown": "\n\nSKU\nWH-2847-BLK\n\n\n\nQUANTITY\n\n48 Units\n\n\n\n<::scan_code: Barcode\n\nThis is a clear, well-defined linear barcode with distinct black bars on a white background, showing no visible quality issues.::>\n\n\n\n2847 0000 4812\n---\n",
"chunks": [
"69a645fe-8617-4be8-b66f-68d7788755c0",
"bdaf2198-0fdc-4c94-be54-a49ca796ea0f",
"65fe085e-b8c8-46e0-848c-f0c32ccf16e8",
"9e551c40-3eaa-4d77-a219-50b7f4a57e05"
]
}
],
"grounding": {
"69a645fe-8617-4be8-b66f-68d7788755c0": {
"box": {
"left": 0.06628379225730896,
"top": 0.09509064257144928,
"right": 0.4664609134197235,
"bottom": 0.2678269147872925
},
"page": 0,
"type": "chunkText"
},
"bdaf2198-0fdc-4c94-be54-a49ca796ea0f": {
"box": {
"left": 0.06750398874282837,
"top": 0.3068091869354248,
"right": 0.3204823434352875,
"bottom": 0.47341251373291016
},
"page": 0,
"type": "chunkText"
},
"65fe085e-b8c8-46e0-848c-f0c32ccf16e8": {
"box": {
"left": 0.11207544803619385,
"top": 0.5374823212623596,
"right": 0.8830909729003906,
"bottom": 0.8660760521888733
},
"page": 0,
"type": "chunkScanCode"
},
"9e551c40-3eaa-4d77-a219-50b7f4a57e05": {
"box": {
"left": 0.28996485471725464,
"top": 0.9088556170463562,
"right": 0.7057502269744873,
"bottom": 0.9888754487037659
},
"page": 0,
"type": "chunkText"
}
},
"metadata": {
"filename": "pallet-label.png",
"org_id": null,
"page_count": 1,
"duration_ms": 4226,
"credit_usage": 3,
"job_id": "y2xvbwlqc1p9ynwfkx4tx7q7q",
"version": "dpt-2-20250919"
}
}
```
## Markdown Structure
The `markdown` field includes a parsed chunk or a sequence of chunks.
Each chunk begins with an [HTML anchor tag](#anchor-tags) containing a unique identifier, followed by the chunk content.
For example, the following `markdown` field contains two chunks:
* A figure chunk (ID: `4c29090b-b75e-4d5f-95b6-24a7d5668486`) with a description of the image
* A text chunk (ID: `ae2e4e41-9443-4fb5-bced-199915f97dec`) containing formatted address information
```json theme={null}
"markdown": "\n\n<::An illustration of a sun with eight rays extending outwards.: figure::>\n\n\n\n**Eliza Smith**\n123 Main St.\nMountain View, CA 94041"
```
### Anchor Tags
Each chunk begins with an HTML anchor tag containing the chunk's unique identifier.
The `id` attribute contains the UUID that matches the corresponding entry in the `chunks` array, enabling you to trace content back to its location in the original document.
```html theme={null}
```
### Content Format by Chunk Type
The Markdown content format varies based on the [chunk type](./ade-chunk-types):
* [Text-Based Chunks](#text-based-chunks)
* [Image-Based Chunks](#image-based-chunks)
* [Table Chunks](#table-chunks)
* [Spreadsheets](#spreadsheets)
#### Text-Based Chunks
For text-based chunks (`text`, `marginalia`), content appears as standard Markdown text:
```markdown theme={null}
## Heading Text
Paragraph content with **bold** and *italic* formatting.
```
#### Image-Based Chunks
Image-based chunks (`figure`, `logo`, `card`, `attestation`, `scan_code`) use a special delimiter format that wraps the caption or description:
```markdown theme={null}
<::Caption or description of the visual element: figure::>
```
#### Table Chunks
Table chunks (`table`) appear as HTML table markup.
Most table elements include unique `id` attributes. These IDs use the format `{page_number}-{base62_sequential_number}`, where the page number starts at 0 and the sequential number increments for each element within the page.
If a page contains multiple tables, the ID numbering continues sequentially across all tables on that page.
Table cells that span multiple rows or columns include `rowspan` or `colspan` attributes in the HTML markup.
This ID system allows you to trace individual cells, rows, and tables back to their locations in the original document. The [JSON response](./ade-json-response#table-cell-position-information) also includes position information (row, column, rowspan, colspan) for each table cell in the grounding object.
```markdown theme={null}
| Product Summary | |
| Product | Revenue |
| Hardware | 15,230 |
| Software | 8,540 |
```markdown theme={null}
{
"markdown": "\n\n| Program | \nInterest Rate | \n
| 15 Year Fixed-Rate Mortgage | \n0.05125 | \n
| 30 Year Fixed-Rate Mortgage | \n0.05875 | \n
| 10/1 ARM | \n0.05625 | \n
2. Copy the script for the method you plan on using: the [ade-python library](./ade-python#extract-getting-started) or the [API](#use-ade-extract-to-extract-fields-from-markdown).
3. Paste the script into your code.
## Use the ADE Extract API to Extract Fields from Markdown
Use the ADE Extract API to extract data from the Markdown output created by the [ADE Parse API](./parse).
See the full ADE Extract API reference [here](https://docs.landing.ai/api-reference/tools/ade-extract).
### Specify Documents to Run Extraction On
The ADE Extract API offers two parameters for specifying the document you want to extract from:
* `markdown`: Specify the actual Markdown file you want to run extraction on.
* `markdown_url`: Include the URL to the Markdown file you want to run extraction on.
### Set the Extraction Schema
Set the extraction schema in the `schema` parameter. The schema must meet specific format and property requirements. For detailed guidance, see [JSON Schema for Extraction](./ade-extract-schema-json).
### Set the `strict` Parameter
Use the optional `strict` parameter to control how the API handles schemas that include [keywords that cause errors](./ade-extract-schema-json#keywords-that-cause-errors).
* If `strict` is `false`: the API continues processing and returns a `206` (Partial Content).
* If `strict` is `true`: the API stops processing and returns a `422` (Unprocessable Entity).
In both cases, the API returns `422` if the schema fails validation, and `206` if the extracted output does not conform to the schema after extraction completes.
### Extracted Output
For details about the extraction response structure and fields, see [JSON Response for Extraction](./ade-extract-response).
## Run Extract with Our Libraries
Click one of the tiles below to learn how to run the [ADE Extract API](https://docs.landing.ai/api-reference/tools/ade-extract) with our libraries.
}
href="./ade-typescript#extract-getting-started"
>
Run Extract with our TypeScript library.
If one of the `anyOf` types is `null`, the API removes `null` and sets the `type` to the other specified type.
If none of the types are `null`, the API falls back to `string`, since that is least likely to cause issues. | | `default` | If `default` is `null`, the API removes the keyword. If `default` is any other value, the API returns a 206. | | `nullable` | The API removes the keyword. All fields are nullable by default. For more information, see [Missing Fields and Nullable Fields](#missing-fields-and-nullable-fields). | | `required` | The API removes the keyword. The API considers all fields to be required. | | `title` | The API removes the keyword. Typically, the title does not give additional information that is not already present in the field name or description. | ### Keywords That Cause Errors Whether the API returns a `206` (Partial Content) or `422` (Unprocessable Entity) depends on the `strict` parameter. If `strict` is `false`, the API returns a `206`. If `strict` is `true`, the API returns a `422`. For more information, see [Set the strict Parameter](./ade-extract#set-the-strict-parameter). **Any keyword not listed in [Supported Keywords](#supported-keywords) or [Ignored Keywords](#ignored-keywords) will cause the API to return an error.** The following list provides common examples and is not exhaustive: * `allOf` * `const` * `maxItems` * `maxLength` * `maximum` * `minItems` * `minLength` * `minimum` * `oneOf` * `pattern` * `propertyOrdering` * `uniqueItems` ## How the API Handles Required Fields The ADE Extract API treats all fields as required and always attempts to extract every property defined in your schema. The `required` keyword is not supported and is ignored if included. For more information, see [Ignored Keywords](#ignored-keywords). If the API cannot find a field in the document, it returns `null` rather than an error. For more information, see [How the API Handles Missing Fields](#how-the-api-handles-missing-fields). ## How the API Handles Missing Fields All fields are nullable, meaning the API returns `null` when it cannot find a field in the document rather than returning an error. Because of this, the API ignores `null` and `nullable` if included in your schema. For more information, see [Ignored Keywords](#ignored-keywords). For example, if your schema includes a `first_name` field but the document does not contain a first name, the API returns `null` for that field. The exact behavior depends on the field type: | Field type | Behavior when not found | | ----------------------------------------------------------- | ----------------------------------------------------------------------- | | Primitive fields (`boolean`, `integer`, `number`, `string`) | Returns `null`. | | `array` | Returns an empty array: `[]`. | | `object` | Never returns `null`, but all primitive fields within it return `null`. | ## Schema Validation The API processes your schema and output in three stages: * [Before Extraction: Validate Schema Structure](#validate-schema-structure-before-extraction) * [During Processing: Convert Schema](#convert-schema-during-processing) * [After Extraction: Validate Extracted Output Against Schema](#validate-extracted-output-against-schema-after-extraction) ### Validate Schema Structure (Before Extraction) The API checks that your schema is valid JSON and follows the required structure. If validation fails, the API returns a `422` error before processing begins. ```json theme={null} { "error": "Invalid JSON schema provided for fields_schema." } ``` ### Convert Schema (During Processing) The API converts your schema before running extraction. If the schema includes [keywords that cause errors](#keywords-that-cause-errors), the behavior depends on the `strict` parameter: * If `strict` is `false`: the API continues and returns a `206` (Partial Content). * If `strict` is `true`: the API stops and returns a `422` (Unprocessable Entity). For more information, see [Set the strict Parameter](./ade-extract#set-the-strict-parameter). ### Validate Extracted Output Against Schema (After Extraction) After extraction completes, the API validates that the extracted output matches your schema. If it does not, the API returns a `206` (Partial Content) with any successfully extracted data. Because the API returns at least partial results, the API call consumes credits. ## FAQs for Extraction Schemas ### Does the order of properties in the schema need to match the order of the fields in the document? No. The order of properties in the schema has no impact on extraction. For example, a property defined last in the schema can still extract data from a field that appears at the top of the document. ### Is there a maximum number of fields that can be extracted? No. There is no maximum number of properties in an extraction schema. ### Can I put formatting and alternative names in the description field? You can include formatting instructions and alternative field names in `description`, but using the dedicated `format` and `x-alternativeNames` keywords is more effective. When you use dedicated keywords, the API knows exactly what each piece of information is: `format` contains only formatting instructions, and `x-alternativeNames` contains only alternative field labels. This allows the API to apply each more precisely than if the same information were embedded in a general description. For more information, see [Format](#format) and [Alternative Names](#alternative-names). ### What is the best practice for writing field descriptions? Be as specific as needed so there is no ambiguity about what to extract. Think of it as natural-language instructions (like prompting an LLM). The clearer and more specific it is, the better the results. You may want to iterate on your descriptions to find what works best for your use case. For more information, see [Field Descriptions](#field-descriptions). ## Earlier Versions of Extract The supported schema structure for the ADE Extract API has changed over time. Extraction schemas generated by Agentic Document Extraction before April 2, 2026 may not be compatible with the current API. Update your schema to meet the requirements described in this article. # Extraction Model Versions Source: https://docs.landing.ai/ade/ade-extract-models Choose an extraction model and set it when running extraction. An extraction model powers the field extraction capabilities of the [ADE Extract](https://docs.landing.ai/api-reference/tools/ade-extract) API. It analyzes your Markdown content and extracts structured data according to your JSON schema. You can specify a model when calling the [ADE Extract](https://docs.landing.ai/api-reference/tools/ade-extract) API directly or when using the [client libraries](#set-the-model-with-the-client-libraries). If you don't specify a model, the API uses the latest extraction model (currently `extract-20260314`). ```shell {5} theme={null} curl -X POST 'https://api.va.landing.ai/v1/ade/extract' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'schema=...' \ -F 'markdown=@markdown.md' \ -F 'model=extract-20260314' ``` ## Model Versions The following table lists the available `model` values for the ADE Extract API: | Model Values | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `extract-20260903` | Use the extraction model snapshot released on September 3, 2026, on an updated underlying model. For more information, go to [extract-20260903](#extract-20260903). | | `extract-20260314` | Use the extraction model snapshot released on March 14, 2026. For more information, go to [extract-20260314](#extract-20260314). This is the default model. | | `extract-latest` | Use the latest extraction model snapshot. |
3. Upload files and click **Create Project**. (Continue to the next step while the files are parsed in the background.)
4. (Optional) Enter natural-language instructions for the extraction in the **Guidelines** text box. This can include:
* Data to include
* Data to exclude
* Context about the files
5. Click **Suggest Schema**.
6. The app reviews the files in the project and creates a master schema. Review the generated fields before continuing.
7. Click [**Run This File**](#run-the-schema-on-your-files) to validate the schema on the selected file.
8. When the schema is ready, [use the schema](#use-the-schema).
### Upload a Schema
If you have an existing extraction schema you want to edit, you can upload it to the Playground to validate it. You can then edit it just like any schema created in the Playground.
**Start a new project with your own schema**
To start with your own extraction schema:
1. Go to the [Playground](https://ade.landing.ai/).
2. Click the **Extract** tile.
3. Upload files and click **Create Project**. (Continue to the next step while the files are parsed in the background.)
4. Click **Upload JSON Schema**.
5. Select the JSON file you want to load.
6. The app loads the JSON file into the **Schema** panel.
**Upload a schema to an existing project**
You can also upload a schema after you've started building one. The uploaded schema is saved as a new version.
To upload a schema to an existing project:
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Extract** tab.
4. In the **Schema** panel, click **...** and select **Import Schema**.
5. Select the JSON file you want to load.
6. The app loads the JSON file into the **Schema** panel.
## Edit and Validate the Schema
After creating a schema in the [Playground](https://ade.landing.ai/), you can edit and validate it. You can add fields, update descriptions, remove fields, and validate the full schema.
* [Edit, Add, or Remove Fields Manually](#edit-add-or-remove-fields-manually)
* [Refine Schema with AI](#refine-schema-with-ai)
* [Run the Schema on Your Files](#run-the-schema-on-your-files)
* [Start Over](#start-over)
### Edit, Add, or Remove Fields Manually
Click a field to see and edit additional information, like the format, description, and alternative names. For detailed information about the field options, go to [Extraction Schema (JSON)](./ade-extract-schema-json).
To add, edit, or remove fields:
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Extract** tab.
4. If you have multiple versions of the schema, make sure that the schema you want to use is selected.
5. Make your changes:
* **Add a field**: Scroll to the bottom of the **Schema** panel and click **New Field**.
* **Edit a field**: Click the field and update it.
* **Remove a field**: Hover over the field and click the **Delete** icon.
6. After making any changes to the schema, click **Update Schema**.
### Refine Schema with AI
### Run the Schema on Your Files
The **Extracted Results** panel refreshes and displays two sets of content:
* **Extraction**: The list of extracted key-value pairs.
* **Extract Metadata**: The key-value pairs and their unique IDs (`references`).
For more information about extraction output, go to [JSON Response for Extraction](./ade-extract-response).
### Start Over
After you create a schema, you can start over. This creates a new blank schema, saved as the next version, while retaining all existing schema versions. You can then manually add fields, refine the schema with AI, or import a schema.
To start over:
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Extract** tab.
4. In the **Schema** panel, click **...** and select **Start Over**.
5. When prompted, click **Start Fresh**.
## Use the Schema
After you create and validate a schema, you are ready to use it.
* [Get a Ready-to-Use Parse and Extract Script](#get-a-ready-to-use-parse-and-extract-script): Get a ready-to-use script for Parse and Extract that uses the schema you created.
* [Export the Schema](#export-the-schema): Download the schema as a JSON file to use in your own code.
### Get a Ready-to-Use Parse and Extract Script
After you create a schema, Agentic Document Extraction generates a script that covers both the [ADE Parse](./parse) and [ADE Extract](./ade-extract) steps using the schema you built. The Playground provides two versions: one for calling the APIs directly, and one for the [ade-python library](./ade-python).
**To get the script:**
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Extract** tab.
4. If you have multiple versions of the schema, make sure that the schema you want to use is selected.
5. Click **Code**.
6. The **View Code** pop-up opens. Click the **Library** or **API** tab to see the code for each extraction method.
7. Click the **Download** or **Copy** buttons to get the code.
### Export the Schema
After you create a schema, you can export it as a downloadable JSON file to use in your own code.
**To export the schema:**
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Extract** tab.
4. If you have multiple versions of the schema, make sure that the schema you want to use is selected.
5. In the **Schema** panel, click **...** and select **Export Schema**.
6. The extraction schema is downloaded as a JSON file.
## Schema Versions
The Playground saves a new version of the schema each time you run **Suggest Schema**, **Refine Schema**, or import a schema. Previous versions are retained even after you use **Start Over**.
Use schema versions to compare results or roll back to an earlier version if a schema update doesn't perform as expected.
To view a previous version, click the drop-down menu in the **Schema** panel and select the version you want to see.
## Download or Copy Extracted Data
You can download or copy extracted data directly from the Playground. This is useful for spot-checking results during schema development. For production use, retrieve extracted data through the [ADE Extract API](./ade-extract) or [ade-python library](./ade-python).
To download or copy the extracted data:
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Extract** tab.
4. If the **Extracted Results** panel doesn't display, create or edit a schema and click **Run This File**.
5. Click the **Download** or **Copy** buttons to get the extracted data.
# Build Extraction Schemas with the API
Source: https://docs.landing.ai/ade/ade-extract-schema-api
Generate a JSON extraction schema programmatically from parsed Markdown with the Build Extract Schema API.
Use the [ADE Build Extract Schema API](https://docs.landing.ai/api-reference/tools/ade-build-schema) to programmatically generate a JSON extraction schema from the Markdown output of the [ADE Parse API](./parse).
The API analyzes the Markdown content and returns a schema you can pass directly to the [ADE Extract API](./ade-extract).
5. The **View Code** pop-up opens. Click the **Library** or **API** tab to see the code for each method.
6. Click the **Download** or **Copy** buttons to get the code.
### Export the Class Schema to JSON
After you create a class schema, you can export it as a JSON file that you can pass to the `classes` parameter in the [API](#classify-with-the-api), [Python library](./ade-python#classify-getting-started), or [TypeScript library](./ade-typescript#classify-getting-started).
**To export the schema:**
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Classify** tab.
4. In the **Schema** panel, click **...** and select **Download Classes**. The classes and descriptions are downloaded as a JSON file.
## Classify with the API
Classify the pages in a document by calling the [ADE Classify](https://docs.landing.ai/api-reference/tools/ade-classify) endpoint.
This example classifies a document that may contain invoices, bank statements, and earnings statements. The `invoice` and `bank_statement` classes include descriptions; `earnings statement` does not.
```shell theme={null}
curl -X POST 'https://api.va.landing.ai/v1/ade/classify' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'classes=[{"class":"invoice","description":"A commercial bill with line items, totals, and payment terms"},{"class":"bank_statement","description":"A monthly summary of account transactions"},{"class":"earnings statement"}]' \
-F 'document=@document.pdf'
```
### Parameters
Get the full parameters from the [API reference](https://docs.landing.ai/api-reference/tools/ade-classify).
| Parameter | Required | Description |
| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `document` | Required (choose one) | The document file to classify. |
| `document_url` | Required (choose one) | A URL pointing to the document to classify. |
| `classes` | Required | A JSON array of class objects. Each object requires a `class` name and accepts an optional `description`. Pass as a JSON string in form data. |
| `model` | Optional | The classification model version to use (for example, `classify-20260420`). Defaults to the latest version. |
## Use Classify with Our Libraries
Click one of the tiles below to learn how to use the [ADE Classify](https://docs.landing.ai/api-reference/tools/ade-classify) API with our libraries.
}
href="./ade-typescript#classify-getting-started"
>
Use ADE Classify with our TypeScript library.
### Get a Ready-to-Use Section Script
After you create a table of contents, Agentic Document Extraction generates a script to section files using the current guideline (if any). The Playground provides two versions: one for calling the API directly, and one for the [ade-python library](./ade-python).
**To get the script:**
1. Go to the [Playground](https://ade.landing.ai/).
2. Open a project.
3. Click the **Section** tab.
4. Click **Get Code**.
5. The **View Code** pop-up opens. Click the **Library** or **API** tab to see the code for each method.
6. Click the **Download** or **Copy** buttons to get the code.
## Section with the API
Section a document by calling the [ADE Section](https://docs.landing.ai/api-reference/tools/ade-section) endpoint.
```shell theme={null}
curl -X POST 'https://api.va.landing.ai/v1/ade/section' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'markdown=@parsed_output.md' \
-F 'model=section-latest'
```
### Parameters
Get the full parameters from the [API reference](https://docs.landing.ai/api-reference/tools/ade-section).
| Parameter | Required | Description |
| :------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `markdown` | Required if `markdown_url` omitted | The Markdown output from the [ADE Parse API](https://docs.landing.ai/api-reference/tools/ade-parse). Accepts a file upload or a raw string. |
| `markdown_url` | Required if `markdown` omitted | A URL pointing to a Markdown file to fetch and section. |
| `guidelines` | Optional | Natural-language instructions that control how the hierarchy is built. When omitted, the API infers structure automatically. Examples: • `"Treat each numbered article as a top-level section"`
• `"Create a flat structure, no more than 2 levels deep"`
• `"Separate the introduction and appendices from the main body"` | | `model` | Optional | The section model version to use. If omitted, the API uses the latest model. For more information, see [Section Model Versions](./ade-section-models). | For detailed information about the API response, go to [JSON Response for Sectioning](./ade-section-response).
}
href="./ade-typescript#section-getting-started"
>
Use ADE Section with our TypeScript library.
ADE Section analyzed the full document and returned a hierarchical table of contents. The **Declarations And Policy Overview** section on the first page appears as section `2` (level 1) in the response.
**Insured Property** and **Policy Period And Renewal** are its level 2 subsections, each with their own level 3 sub-subsections.
Each entry's `start_reference` points to the chunk where that section begins in the parsed document.
```json [expandable] theme={null}
{
"table_of_contents": [
{
"title": "Policy Header",
"level": 1,
"section_number": "1",
"start_reference": "1c4b7184-346d-490f-a7bf-bf2442bcbd7c"
},
{
"title": "Declarations And Policy Overview",
"level": 1,
"section_number": "2",
"start_reference": "494d766e-5cf1-48c4-a580-73061b722b90"
},
{
"title": "Insured Property",
"level": 2,
"section_number": "2.1",
"start_reference": "1e6c9100-f461-4bb8-8dcd-8ae0311a97c0"
},
{
"title": "Mortgage And Lienholder",
"level": 3,
"section_number": "2.1.1",
"start_reference": "95e79ad7-72b5-4c9f-9717-8488996c6795"
},
{
"title": "Detached Structures",
"level": 3,
"section_number": "2.1.2",
"start_reference": "4c1e087b-aee9-4494-9789-735388a7579c"
},
{
"title": "Policy Period And Renewal",
"level": 2,
"section_number": "2.2",
"start_reference": "de55b7d5-df5c-480e-8b91-0f9f10f5b059"
},
{
"title": "Cancellation",
"level": 3,
"section_number": "2.2.1",
"start_reference": "7cc48544-b2ec-4e34-b2a1-ae1b3b7d17a6"
},
{
"title": "Annual Premium",
"level": 3,
"section_number": "2.2.2",
"start_reference": "b8c0ba71-d786-4f89-a07f-3fcfc0edd734"
},
{
"title": "Schedule Of Coverages And Limits",
"level": 1,
"section_number": "3",
"start_reference": "3700c26c-dd67-4dda-a712-081becb9ab63"
},
{
"title": "Coverage A Dwelling",
"level": 2,
"section_number": "3.1",
"start_reference": "de789af4-1585-4b3f-9193-4253a9e58f6b"
},
{
"title": "Ordinance Or Law",
"level": 3,
"section_number": "3.1.1",
"start_reference": "c7eaad71-19ca-4ab4-90cb-e8e9581ededc"
},
{
"title": "Named Storm Deductible",
"level": 3,
"section_number": "3.1.2",
"start_reference": "d1300436-0131-49d1-a98a-1f46ece31c23"
},
{
"title": "Coverage C Personal Property",
"level": 2,
"section_number": "3.2",
"start_reference": "80ed234f-1824-4def-b7fb-6883c3fa2b52"
},
{
"title": "Sub Limits",
"level": 3,
"section_number": "3.2.1",
"start_reference": "0c3e0c5a-80ee-49f6-9ca5-52941547d4bd"
},
{
"title": "Business Property",
"level": 3,
"section_number": "3.2.2",
"start_reference": "60aba72b-ca56-4806-97b0-bdf580669943"
},
{
"title": "Exclusions",
"level": 1,
"section_number": "4",
"start_reference": "29529f14-e489-4f2a-bea8-0eef68f431b0"
},
{
"title": "Earth Movement And Flood",
"level": 2,
"section_number": "4.1",
"start_reference": "51c3a6b7-7b78-404e-a1f3-b39be8498294"
},
{
"title": "Ensuing Loss",
"level": 3,
"section_number": "4.1.1",
"start_reference": "908cf899-f5af-40c8-9829-4e09da9083c9"
},
{
"title": "Concurrent Causation",
"level": 3,
"section_number": "4.1.2",
"start_reference": "f48d2861-3d9a-4db6-b2d1-78d22013c3fb"
},
{
"title": "Other Exclusions",
"level": 2,
"section_number": "4.2",
"start_reference": "3336ee6d-9723-4fe1-914f-75109187cc0a"
},
{
"title": "Wear And Tear",
"level": 3,
"section_number": "4.2.1",
"start_reference": "f66ab1c5-d5fe-42ac-bf71-56a3c769a0a6"
},
{
"title": "Vacancy",
"level": 3,
"section_number": "4.2.2",
"start_reference": "75eff73f-3166-45dd-9140-a9182f858e47"
},
{
"title": "Claims And Conditions",
"level": 1,
"section_number": "5",
"start_reference": "35ccfa20-00fb-462e-b375-aaa1b84a1d8f"
},
{
"title": "Duties After A Loss",
"level": 2,
"section_number": "5.1",
"start_reference": "a08d6602-32b0-41e0-ad85-5d951dfc93c0"
},
{
"title": "Notice Deadline",
"level": 3,
"section_number": "5.1.1",
"start_reference": "a68996f1-acd7-403e-bb68-58a7fbe336f0"
},
{
"title": "Emergency Repairs",
"level": 3,
"section_number": "5.1.2",
"start_reference": "edd78fe8-08d6-4f55-a19b-d15a2a05464b"
},
{
"title": "Dispute Resolution",
"level": 2,
"section_number": "5.2",
"start_reference": "bdf63da4-4f34-48f0-82a2-cece1ef666d0"
},
{
"title": "Suit Limitation",
"level": 3,
"section_number": "5.2.1",
"start_reference": "db860fc2-e02e-4efa-8205-553b392b63ca"
},
{
"title": "Loss Payment",
"level": 3,
"section_number": "5.2.2",
"start_reference": "0f7081fd-75c2-4e0f-8355-b4d66a13c20f"
},
{
"title": "Policyholder Acknowledgment",
"level": 1,
"section_number": "6",
"start_reference": "065d0342-0c5b-4fbc-9888-b78ac5e0fefc"
},
{
"title": "Signature Lines",
"level": 1,
"section_number": "7",
"start_reference": "f47e4117-eda0-477d-9a76-482bff511444"
}
],
"table_of_contents_md": "- [Policy Header](#1c4b7184-346d-490f-a7bf-bf2442bcbd7c)\n- [Declarations And Policy Overview](#494d766e-5cf1-48c4-a580-73061b722b90)\n - [Insured Property](#1e6c9100-f461-4bb8-8dcd-8ae0311a97c0)\n - [Mortgage And Lienholder](#95e79ad7-72b5-4c9f-9717-8488996c6795)\n - [Detached Structures](#4c1e087b-aee9-4494-9789-735388a7579c)\n - [Policy Period And Renewal](#de55b7d5-df5c-480e-8b91-0f9f10f5b059)\n - [Cancellation](#7cc48544-b2ec-4e34-b2a1-ae1b3b7d17a6)\n - [Annual Premium](#b8c0ba71-d786-4f89-a07f-3fcfc0edd734)\n- [Schedule Of Coverages And Limits](#3700c26c-dd67-4dda-a712-081becb9ab63)\n - [Coverage A Dwelling](#de789af4-1585-4b3f-9193-4253a9e58f6b)\n - [Ordinance Or Law](#c7eaad71-19ca-4ab4-90cb-e8e9581ededc)\n - [Named Storm Deductible](#d1300436-0131-49d1-a98a-1f46ece31c23)\n - [Coverage C Personal Property](#80ed234f-1824-4def-b7fb-6883c3fa2b52)\n - [Sub Limits](#0c3e0c5a-80ee-49f6-9ca5-52941547d4bd)\n - [Business Property](#60aba72b-ca56-4806-97b0-bdf580669943)\n- [Exclusions](#29529f14-e489-4f2a-bea8-0eef68f431b0)\n - [Earth Movement And Flood](#51c3a6b7-7b78-404e-a1f3-b39be8498294)\n - [Ensuing Loss](#908cf899-f5af-40c8-9829-4e09da9083c9)\n - [Concurrent Causation](#f48d2861-3d9a-4db6-b2d1-78d22013c3fb)\n - [Other Exclusions](#3336ee6d-9723-4fe1-914f-75109187cc0a)\n - [Wear And Tear](#f66ab1c5-d5fe-42ac-bf71-56a3c769a0a6)\n - [Vacancy](#75eff73f-3166-45dd-9140-a9182f858e47)\n- [Claims And Conditions](#35ccfa20-00fb-462e-b375-aaa1b84a1d8f)\n - [Duties After A Loss](#a08d6602-32b0-41e0-ad85-5d951dfc93c0)\n - [Notice Deadline](#a68996f1-acd7-403e-bb68-58a7fbe336f0)\n - [Emergency Repairs](#edd78fe8-08d6-4f55-a19b-d15a2a05464b)\n - [Dispute Resolution](#bdf63da4-4f34-48f0-82a2-cece1ef666d0)\n - [Suit Limitation](#db860fc2-e02e-4efa-8205-553b392b63ca)\n - [Loss Payment](#0f7081fd-75c2-4e0f-8355-b4d66a13c20f)\n- [Policyholder Acknowledgment](#065d0342-0c5b-4fbc-9888-b78ac5e0fefc)\n- [Signature Lines](#f47e4117-eda0-477d-9a76-482bff511444)\n",
"metadata": {
"filename": "insurance_policy-md.md",
"org_id": "org_123",
"duration_ms": 15435,
"credit_usage": 6.0588,
"job_id": "17aa1381fe97495f8b9be76baba9932c",
"version": "section-20260406"
}
}
```
## Response Structure
The response contains the following top-level fields:
| Field | Description |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [`table_of_contents`](#table-of-contents-table_of_contents) | A flat, reading-order array of section entries with hierarchy levels and chunk references. |
| [`table_of_contents_md`](#markdown-table-of-contents-table_of_contents_md) | A Markdown-formatted version of the same TOC with anchor links. |
| [`metadata`](#processing-metadata-metadata) | Processing information including credit usage, duration, filename, job ID, and model version. |
## Table of Contents (`table_of_contents`)
The `table_of_contents` field contains a flat array of all sections and subsections in the order they appear in the document. The flat list structure is optimized for retrieval use cases. You can iterate the list directly without recursion.
Each entry includes:
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | The generated text for the section heading. |
| `level` | The hierarchy depth. Top-level sections are `1`, subsections are `2`, sub-subsections are `3`, and so on. |
| `section_number` | The hierarchical number for this section (for example, `"1"`, `"1.2"`, `"1.2.3"`). Use this field to reconstruct parent-child relationships: entry `"2.1"` is a child of entry `"2"`. |
| `start_reference` | The ID of the chunk where this section begins. This corresponds to a `chunks[].id` value from the [ADE Parse API](https://docs.landing.ai/api-reference/tools/ade-parse) response. |
## Markdown Table of Contents (`table_of_contents_md`)
The `table_of_contents_md` field provides a ready-to-use Markdown-formatted TOC. Each entry is an anchor link pointing to the corresponding [reference anchor](./ade-markdown-response#anchor-tags) in the document Markdown. Indentation represents the hierarchy level.
You can prepend this string to the document's full Markdown to enable in-document navigation:
```text theme={null}
- [Introduction](#uuid_a1)
- [Methods](#uuid_b2)
- [Data Collection](#uuid_c3)
- [Survey Design](#uuid_d4)
```
## Processing Metadata (`metadata`)
The `metadata` field provides information about the sectioning process:
| Field | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `filename` | The name of the input Markdown file. |
| `org_id` | Organization identifier. |
| `duration_ms` | Processing time in milliseconds. |
| `credit_usage` | Number of credits consumed. |
| `job_id` | Unique job identifier. |
| `version` | Model version used for sectioning. For more information, go to [Section Model Versions](./ade-section-models). |
# Troubleshoot Sectioning
Source: https://docs.landing.ai/ade/ade-section-troubleshoot
Resolve Section API errors using status codes, causes, and recommended fixes.
Use this section to troubleshoot issues encountered when calling the [ADE Section](https://docs.landing.ai/api-reference/tools/ade-section) API ([https://api.va.landing.ai/v1/ade/section](https://api.va.landing.ai/v1/ade/section)).
## Status Codes
| Status Code | Name | Description | What to Do |
| ----------- | --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 | Success | Sectioning completed successfully. | Continue with normal operations. |
| 400 | Bad Request | Invalid request due to Markdown download failure from URL. | Review error message for specific issue. See [Status 400](#status-400-bad-request). |
| 401 | Unauthorized | Missing or invalid API key. | Check that your `Authorization` header is present and contains a valid [API key](./agentic-api-key). |
| 402 | Payment Required | Your account does not have enough credits to complete processing. | If you have multiple accounts, make sure you're using the correct [API key](./agentic-api-key). Add more credits to your account. |
| 422 | Unprocessable Entity | Input validation failed. | Review your request parameters. See [Status 422](#status-422-unprocessable-entity). |
| 429 | Too Many Requests | Rate limit exceeded. | Wait before retrying. Reduce request frequency and implement exponential backoff. |
| 500 | Internal Server Error | Server error during sectioning. | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai). See [Status 500](#status-500-internal-server-error). |
| 504 | Gateway Timeout | Request processing exceeded the timeout limit. | Reduce Markdown content size. See [Status 504](#status-504-gateway-timeout). |
## Status 400: Bad Request
This status code indicates a client-side error. Review the specific error message to identify the issue.
### Error: Failed to download document from URL
This error occurs when the API cannot download the Markdown file from the provided `markdown_url`.
**Error message:**
```
Failed to download document from URL: {error_details}
```
**What to do:**
* Verify the URL is accessible and returns valid content.
* Check network connectivity and URL permissions.
* Ensure the URL points to a Markdown file (.md extension).
## Status 422: Unprocessable Entity
This status code indicates input validation failures. Review the error message and adjust your request parameters.
### Error: No markdown provided
This error occurs when your request does not include the `markdown` parameter or `markdown_url` parameter, or when the values are empty.
**Error message:**
```
Must provide either 'markdown' or 'markdown_url'.
```
**What to do:**
Add one of these parameters to your request:
* Use the `markdown` parameter to upload a Markdown file or provide inline Markdown content, OR
* Use the `markdown_url` parameter to provide a URL to a Markdown file.
### Error: Both 'markdown' and 'markdown\_url' provided
This error occurs when your request includes both the `markdown` and `markdown_url` parameters.
**Error message:**
```
Cannot provide both 'markdown' and 'markdown_url'.
```
**What to do:**
Remove one of the parameters. Use either `markdown` (to upload a file or provide inline content) or `markdown_url` (to specify a URL), but not both in the same request.
### Error: Invalid 'markdown\_url' format
This error occurs when the value provided for `markdown_url` is not a valid URL.
**Error message:**
```
Invalid URL format: {url}
```
**What to do:**
* Verify that the URL is correctly formatted (for example, `https://example.com/document.md`).
* Ensure the URL includes a scheme (`https://` or `http://`).
### Error: Multiple markdown files detected
This error occurs when multiple Markdown files are included in the request.
**Error message:**
```
Multiple markdown files detected (X). Please provide only one document file.
```
**What to do:**
Send only one Markdown file per request.
### Error: Unsupported format
This error occurs when you provide a file other than Markdown (.md) to the section endpoint.
**Error message:**
```
Unsupported format: {mime_type} ({filename}). Supported formats: MD
```
**What to do:**
* The section endpoint only accepts Markdown files with a .md extension.
* If you have a PDF, DOCX, or other document format, use the [ADE Parse API](https://docs.landing.ai/api-reference/tools/ade-parse) to convert your document to Markdown first, then pass the parsed Markdown output to the section endpoint.
* Ensure your file has a .md extension and contains valid UTF-8 encoded Markdown content.
### Error: Missing reference anchors
This error occurs when the Markdown content does not contain reference anchors. The section endpoint requires Markdown output from the [ADE Parse API](https://docs.landing.ai/api-reference/tools/ade-parse), which includes `` anchors that ADE Section uses to map sections to chunks.
**Error message:**
```
Invalid markdown: missing reference anchors. Markdown must contain reference delimiters. Use the parse tool to generate properly formatted markdown.
```
**What to do:**
* Do not pass plain Markdown or documents you have formatted manually. Use the Markdown output from the [ADE Parse API](https://docs.landing.ai/api-reference/tools/ade-parse) as input.
* Confirm the Markdown content contains `` anchor tags before sending it to the section endpoint.
## Status 500: Internal Server Error
This error indicates an unexpected server error occurred during sectioning.
**What to do:**
* Retry the request.
* If the error persists, contact [support@landing.ai](mailto:support@landing.ai).
## Status 504: Gateway Timeout
This error occurs when the sectioning process exceeds the timeout limit.
**What to do:**
* Reduce the size of your Markdown document.
* If the error persists, contact [support@landing.ai](mailto:support@landing.ai).
## Best Practices for Avoiding Errors
* **Use parsed Markdown**: Always pass Markdown content generated by the [ADE Parse API](./parse). The section endpoint requires structured Markdown with [reference anchors](./ade-markdown-response#anchor-tags) (``).
* **Use guidelines sparingly**: The `guidelines` parameter is optional. Start without guidelines to see the default behavior before customizing the hierarchy.
## When Are Credits Consumed?
Credits are consumed only when the ADE Section API returns a 200 status code. All other responses, including errors, do not consume credits.
# Split
Source: https://docs.landing.ai/ade/ade-split
Separate a parsed document into classified sub-documents by type (Preview).
Use the [ADE Split](https://docs.landing.ai/api-reference/tools/ade-split) API to split a parsed document into multiple classified sub-documents.
Organizations typically use Split when they receive batched documents that contain multiple document types or multiple instances of the same document type. The API classifies each sub-document and returns the full Markdown content for downstream processing.
Splitting occurs after [parsing](https://docs.landing.ai/api-reference/tools/ade-parse) but before [extraction](https://docs.landing.ai/api-reference/tools/ade-extract). You can use Split without performing extraction.
}
href="./ade-typescript#split-getting-started"
>
Use Split with our TypeScript library.
6,000 pages |
| File Type | Playground | API/Library |
|---|---|---|
up to 100 pages |
see [Rate Limits](./ade-rate-limits) |
|
| Images | ||
| JPEG | ||
| JPG | ||
| PNG | ||
| APNG | ||
| BMP | ||
| DCX | ||
| DDS | ||
| DIB | ||
| GD | ||
| GIF | ||
| ICNS | ||
| JP2 (JP2000) | ||
| PCX | ||
| PPM | ||
| PSD | ||
| TGA | ||
| TIF | ||
| TIFF | ||
| WEBP | ||
| Text Documents (see notes [here](#file-conversion-for-text-documents-and-presentations)) |
||
| DOC (Word) | ||
| DOCX (Word) | ||
| ODT (OpenDocument Text) | ||
| Presentations (see notes [here](#file-conversion-for-text-documents-and-presentations)) |
||
| PPT (PowerPoint) | ||
| PPTX (PowerPoint) | ||
| Spreadsheets (see notes [here](#spreadsheet-considerations)) |
||
| CSV (comma-separated values) | (up to 10 MB) |
(up to 50 MB) |
| XLSX (Microsoft Excel) | (up to 10 MB) |
(up to 50 MB) |
Available on Team and Enterprise plans. | #### Spreadsheets The number of credits used to parse a spreadsheet is based on the number of sheets and embedded images. For supported spreadsheet formats, see [Supported File Types](./ade-file-types). | Feature | Credit Cost | Notes | | :-------------- | :----------------------------------- | :--------------------------------------------------------------------------- | | Parsing | 1 credit/sheet | Each sheet processed includes parsing. | | Embedded images | 3 credits/image | Cost per embedded image, chart, or logo. | | ZDR (HIPAA/BAA) | +1 credit/sheet
+1 credit/image | Additional charge when enabled.
Available on Team and Enterprise plans. | **Example:** A spreadsheet with 1 sheet and 2 embedded images: * Base cost: 1 credit (sheet) + 6 credits (2 images) = **7 credits** * With ZDR enabled: 7 credits (base) + 1 credit (sheet) + 2 credits (2 images) = **10 credits** ### Credit Costs for the Extract API This section explains credit use for these APIs: * [ADE Extract API](https://docs.landing.ai/api-reference/tools/ade-extract) * [ADE Extract Jobs](https://docs.landing.ai/api-reference/tools/ade-extract-jobs) The number of credits used to extract data is based on both the number of input characters and output characters, and is rounded up to the nearest tenth decimal place. The same credit costs apply whether you extract data synchronously with the ADE Extract API or asynchronously with the [ADE Extract Jobs](./ade-extract-async) API. | Factor | Credit Cost | Notes | | :---------------------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 5,000 input characters | 1 credit | Input characters are the number of characters in the Markdown file that is passed to the API. | | 1,000 output characters | 1 credit | Output characters are the number of characters in the `extraction` object returned by the API, excluding whitespace used for indentation. (Other spaces, like the spaces after colons in key-value pairs, are not removed.) | **Formula** Here is the formula used to calculate the credit cost: ```text theme={null} credits = (input characters ÷ 5,000) + (output characters ÷ 1,000) Result is rounded up to the nearest tenth decimal place. ``` #### Sample Cost for the Extract API **Input Characters** Let's say you run the ADE Extract API on a Markdown file with the following content. The file has 2,270 characters. Therefore, **the number of input characters is 2,270.** ``` \n\nAROMA CAFE\n1211 Green Street\nNew York, NY 10005\n\n\n\n12/27/2019\n\n\n\n08:26 PM\n\n\n\nTAB 8 HOST MAGGIE\n\n\n\nAMEX ##########19883\n\n\n\n
| QTY | \nDESC | \nAMT | \n
|---|---|---|
| 1 | \nAmericano | \n$3.19 | \n
| 1 | \nAlmond Scone | \n$1.99 | \n
| 1 | \n16oz Bottle Water | \n$2.99 | \n
4. Fill out and submit the request form.
5. The LandingAI team will review the request and contact you with more information.
## Install the App
After you have [requested the app](#request-the-app) and have been granted access to it, follow the instructions below to install it in Snowflake:
1. Go to **Snowsight** > **Catalog** > **Apps** > **Recently Shared with You**.
2. Locate and click the **Agentic Document Extraction - App** listing.
3. Click **Get**.
4. If you want to change the name of the application, click **Options** and enter a name in **Application Name**.
5. Click **Get**.
6. A pop-up indicates that the installation process has begun.
7. After this process is complete, click **Configure** on the pop-up. (You will also get an email notifying you that you can access the app.)
8. The app opens.
9. In the pop-up that displays, grant egress access by clicking **Connect**.
**The app requires this access to function.** Egress access allows the app to connect to the Agentic Document Extraction service over the internet.
5. The app saves the API key, generates procedures for using Agentic Document Extraction, and unlocks usage instructions on the Home page. This might take a few minutes.
## Next Steps
After you install the app and enter your API key in the app, you are ready to [parse documents](./ade-sf-parse-cloud) and [extract data](./ade-sf-extract-cloud).
## App Updates
The app is automatically updated when a new version is released. Users cannot manually update the app.
## Troubleshooting Tips
### Error: Connect to allow the app to access the LandingAI Agentic Document Extraction service
During the installation process, you might get this error:
> Connect to allow the app to access the LandingAI Agentic Document Extraction service
>
> This app requires Internet access to connect to the LandingAI Agentic Document Extraction service. The app will not function without this access.
>
> There was an error initializing the configuration flow. Close the dialog and try again later.
If you get this error message, try selecting a different warehouse from the drop-down menu in the top right corner.
# Parse Documents
Source: https://docs.landing.ai/ade/ade-sf-parse-cloud
Parse documents staged in Snowflake or at public URLs with the api.parse procedure.
## Prerequisites
**In Agentic Document Extraction:**
1. If you haven't already, [create an Agentic Document Extraction account](https://ade.landing.ai/).
2. [Get your API key](https://ade.landing.ai/my/settings/api-key).
**In Snowsight:**
1. [Install the app](./ade-sf-install).
2. [Enter your API key in the app](./ade-sf-install#enter-api-key).
3. If you want to parse documents staged in Snowflake, [grant the app access to the stages that have the files you want to parse](./ade-sf-grant-access-to-stages).
## Set Up the Session
Before running a parse or extract procedure, run the command below to set your session to use the Agentic Document Extraction application and procedures.
Replace this placeholder with the [name of your instance](./ade-sf-app-name) of Agentic Document Extraction: `APP_NAME`.
```sql theme={null}
USE "APP_NAME";
```
## Parse
To parse documents, use the `api.parse` procedure.
The `api.parse` procedure sends a document from a Snowflake stage or publicly accessible URL to the LandingAI-hosted Agentic Document Extraction service, and saves the parsed content to an output table (defaults to `db.parse_output`).
The `api.parse` procedure runs the [ADE Parse Jobs API](./ade-parse-async).
## Optional Parameters
The `api.parse` procedure supports these optional parameters:
* **`model`**: Specify the model version to use for parsing. For full details on parsing models, go to [Document Pre-Trained Transformers (Parsing Models)](./ade-parse-models).
* **`split`**: Specify how to [split](./parse#set-up-splits-for-parsing) the document.
* **`output_table`**: Specify a [custom output table name](#specify-a-custom-output-table) instead of the default `parse_output`.
## Specify a Custom Output Table
You can specify a custom table name for storing parse results instead of using the default `parse_output`:
```sql theme={null}
CALL api.parse(
file_path => 'https://ade.landing.ai/pdfs/invoice_1.pdf',
output_table => 'my_custom_results'
);
SELECT * FROM db.my_custom_results;
```
The procedure automatically creates the table (if it doesn't exist) with the following schema:
* DOC\_ID
* SOURCE\_URL
* FILENAME
* PAGE\_COUNT
* MODEL\_VERSION
* PARSED\_AT
* STATUS\_CODE
* MARKDOWN
* CHUNKS
* SPLITS
* GROUNDING
* METADATA
* ERROR
### Example with Optional Parameters
```sql theme={null}
CALL api.parse(
file_path => 'https://ade.landing.ai/pdfs/invoice_1.pdf',
model => 'dpt-2-latest',
output_table => 'invoice_results'
);
SELECT * FROM db.invoice_results;
```
## Parse Return Object
The `api.parse` procedure returns an OBJECT with the following fields:
* **`message`**: Success or error message
* **`output_table`**: Name of the table where results were saved (such as "db.parse\_output")
* **`doc_id`**: Unique document identifier for the parsed document
* **`status_code`**: HTTP status code for the request
This return object is useful when chaining parse and extract operations together. You can capture the result into a variable and pass it to `api.extract`.
Example of capturing the return object:
```sql theme={null}
DECLARE
result OBJECT;
BEGIN
CALL api.parse(
'https://ade.landing.ai/pdfs/invoice_1.pdf'
) INTO :result;
RETURN result;
END;
```
## Use build\_scoped\_file\_url for Staged Files
You can use the `build_scoped_file_url()` function to reference files in Snowflake stages.
```sql theme={null}
CALL api.parse(
file_path => build_scoped_file_url('@your_db.your_schema.your_stage', '/sample_image.png')
);
SELECT * FROM db.parse_output;
```
## Sample Scenarios
This section provides examples of how to run the `api.parse` procedure in different scenarios.
* [Parse a File at a Publicly Accessible URL](#parse-a-file-at-a-publicly-accessible-url)
* [Parse a Staged File](#parse-a-staged-file)
* [Parse Multiple Staged Files](#parse-multiple-staged-files)
### Parse a File at a Publicly Accessible URL
Run the command below to parse a single file at a publicly accessible URL. We've provided a sample file to help you get started.
Replace this placeholder with your information: `APP_NAME`.
```sql theme={null}
USE "APP_NAME";
CALL api.parse(
'https://ade.landing.ai/pdfs/invoice_1.pdf'
);
SELECT * FROM db.parse_output;
```
### Parse a Staged File
# LandingLens and LandingEdge Documentation
Source: https://docs.landing.ai/landinglens-landingedge
Find LandingLens and LandingEdge documentation, now hosted on a dedicated site.
LandingLens and LandingEdge documentation has moved to this dedicated site: [https://landinglens.docs.landing.ai/](https://landinglens.docs.landing.ai/).
}
href="#typescript"
>
Use concurrent parsing with Promise.all() or p-limit
### Review Low-Confidence Sections
Low-confidence sections (with scores of 0.95 or lower) are highlighted in yellow in the Playground. Highlighting low-confidence sections helps you quickly identify content that may need review.
* **Text, card, marginalia chunks**: Specific text spans within a chunk are highlighted. A single chunk can contain multiple highlighted spans.
* **Tables**: Each cell has its own confidence score. If a cell has a low score, the entire cell is highlighted.
#### Why is 0.95 the threshold for low confidence scores?
The Playground highlights content with confidence scores of 0.95 or lower because this is the threshold used internally to evaluate parsing quality.
This threshold works well for general review workflows, but your use case may require a different threshold. When [using the API](./ade-json-response#confidence-score), you can implement custom logic to identify and route content based on confidence scores that match your specific requirements.
#### Why don't I see the confidence score for files I uploaded in the past?
The confidence score displays for documents parsed on February 12, 2026 or later. If you parsed a document before that date, the Playground does not re-process documents.
If you want to see the newest results for a file that you've already parsed, re-upload it to the Playground.
### Use Confidence Scores in the API Response
The `grounding` object in the API response includes all the confidence information displayed in the Playground:
* Confidence scores for each chunk and table cell
* For text chunks with low-confidence spans: the text, confidence score, and character positions (`start`, `end`) for each span
This allows you to programmatically identify and route low-confidence content for review in your applications. Learn more in [Confidence Scores](./ade-json-response#confidence-score).
## Parsing Status
After loading multiple files into the Playground, a floating dialog box appears in the bottom right corner, showing the parsing progress for each file. If a file fails to process, an error message displays in this area.
## Multiple File Upload Not Available with ZDR
When [Zero Data Retention](./zdr) (ZDR) is enabled, only one file can be loaded at a time.
