Parse API Response

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`	The complete document as a single Markdown string, in reading order.
`metadata`	Information about the job: model version, page count, duration, billing, and more.
`structure`	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` object.

Markdown

The markdown field is a single string containing the document in reading order, following CommonMark 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. Superscript and subscript text that is not part of a math formula is wrapped in <sup> and <sub> tags. When using , math formulas are transcribed as LaTeX, wrapped in $...$ for inline math or $$...$$ for display math, matching the original layout.

Block	Representation
Page break	`<!-- PAGE BREAK -->` appended after each page’s content. Absent in single-page documents.
Document ID	`<!-- doc_id=<job_id> -->` appended as the final line of the output. It carries the parse job’s `job_id` so the Extract v2 API can link an extract call back to the originating parse job.
Table	HTML `<table>` 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: `<figure type="TYPE">` wraps the figure’s transcribed text and one or more generated `<description>...</description>` blocks. See Figures.
Logo	Transcribed text from the logo, with a brief bracketed description for the visual mark (for example, `[Logo with letter A inside shield]`).
Card	Transcribed visible text content from the card.
Scan code	A bracketed code type, followed by the decoded value when it is readable. For example, `[BARCODE]` followed by the digits on the next line.
Attestation	One or more bracketed classification labels on a single header line (for example, `[STAMPED][SIGNED]`), followed by the transcribed content. Printed text is transcribed as prose; a visual-only mark is transcribed as a short bracketed description. See Attestations.

Figures

A figure is wrapped in an HTML-style element whose type attribute is the classification label: <figure type="TYPE">...</figure>. Inside the element, the figure’s visible text is transcribed, and generated descriptions of the visual content appear in <description>...</description> blocks. A CHART figure also transcribes the chart’s data as an HTML <table>. The figure type labels are CHART, FLOWCHART, DIAGRAM, ILLUSTRATION, and PHOTOGRAPH, with FIGURE as the fallback. Example A bar chart could render like this:

<figure type="CHART"><description>Bar chart of quarterly revenue</description></figure>

Attestations

An attestation is a block that has a signature, stamp, or seal. It renders as a header line of one or more bracketed type labels, followed by the block’s transcribed content. The type labels are SIGNED, E-SIGNED, STAMPED, and SEALED. The type labels stack when a block has more than one. Within the content, readable text is transcribed as prose, and every visual mark is replaced by a short bracketed description of what it is. The model generates these descriptions, so treat their wording as variable rather than a fixed set of labels. Two of these descriptions are fixed literals you can build logic around:

[ILLEGIBLE_SIGNATURE]: a signature that can’t be read.
[ILLEGIBLE_TEXT]: any other unreadable text.

Example An attestation block that is both stamped and signed, with a legible and an unreadable signature, could render like this:

[STAMPED][SIGNED]
Secretary of State use only
IDAHO SECRETARY OF STATE
[HANDWRITTEN_SIGNATURE]
[ILLEGIBLE_SIGNATURE]

Structure: Pages and Blocks

The structure field is a document node whose children are pages, and each page’s children are the blocks on that page. Every node below the root document carries its location inline in a grounding object, so hierarchy and spatial data live in one tree.

Common Block Fields

Every block in the structure tree shares the same base shape:

Field	Description
`type`	The block type. See block types below.
`id`	A semantic block identifier, unique within the document, in the format `<type>-<index>`. The index is a per-type counter that starts at 0 and follows reading order: `text-0` is the document’s first text block, `figure-0` is its first figure, and `table_cell-3` is the fourth cell of its first table. Ids are stable within a response but not across re-parses of the same document.
`grounding`	The block’s location: the page it appears on, its `range` in the `markdown` string, and its bounding `box`. See Grounding.
`atomic_grounding`	Finer-grained grounding segments within the block. Present only on leaf blocks (every type except `table`). See Atomic Grounding.
`children`	Child blocks. Present on `document`, `page`, and `table`.
`markdown`	The block’s slice of the top-level `markdown` string. Present only when the request sets `options.inline_markdown` to `true`; an empty string for blocks with zero-length ranges.

Page Fields

page nodes carry their own grounding plus parse status fields:

Field	Description
`grounding`	The page’s location data. The `page` value is the page’s 1-indexed number in the source document, `range` covers the page’s content in the `markdown` string (zero-length for failed pages), and `box` is always the full page: `{"xmin": 0, "ymin": 0, "xmax": 1, "ymax": 1}`.
`status`	`"ok"` if the page was parsed successfully, or `"failed"`.
`reason`	Failure reason. Present only when `status` is `"failed"`.
`children`	The blocks detected on the page, in reading order. Empty for failed pages.

Block Types

recognizes the following block types:

Type	Description
`text`	Any textual content: titles, headings, paragraphs, lists, captions, key-value pairs, form fields, headers, and footers.
`table`	A table. Its `children` are the cells.
`table_cell`	A table cell, present as a child of a `table`. A single type covers every cell; there is no separate header-cell type.
`figure`	An image, chart, diagram, or other non-text visual content.
`marginalia`	Text appearing in the margins, outside the main content flow.
`attestation`	A certification, stamp, or signature region.
`logo`	A company or brand logo.
`card`	A business card or card-like block.
`scan_code`	A QR code, barcode, or other machine-readable code.

Tables and Cells

A table block has its own id and grounding, and a children array of table_cell blocks in row-major order. Every cell uses the table_cell type, including cells in header rows. Each cell carries its grid position:

Field	Description
`row`	0-indexed row position.
`col`	0-indexed column position.
`colspan`	Number of columns the cell spans. Defaults to 1.
`rowspan`	Number of rows the cell spans. Defaults to 1.

Cell positions are 0-indexed even though page numbers are 1-indexed. A table is the one block type that has children but no atomic_grounding of its own. Its cells are leaf blocks that carry it instead: empty with , one entry per word with . See Entries by Block Type. A cell’s range points to its own content in the Markdown, so an empty cell has a zero-length range. In this example, both cells have empty atomic_grounding arrays:

{
  "type": "table",
  "id": "table-0",
  "grounding": {
    "page": 1,
    "range": { "start": 114, "end": 212 },
    "box": { "xmin": 0.08006536, "ymin": 0.21969697, "xmax": 0.91993464, "ymax": 0.42045455 }
  },
  "children": [
    {
      "type": "table_cell",
      "id": "table_cell-0",
      "grounding": {
        "page": 1,
        "range": { "start": 114, "end": 114 },
        "box": { "xmin": 0.08006536, "ymin": 0.21969697, "xmax": 0.27941176, "ymax": 0.27020202 }
      },
      "atomic_grounding": [],
      "row": 0, "col": 0, "colspan": 1, "rowspan": 1
    },
    {
      "type": "table_cell",
      "id": "table_cell-1",
      "grounding": {
        "page": 1,
        "range": { "start": 118, "end": 125 },
        "box": { "xmin": 0.27941176, "ymin": 0.21969697, "xmax": 0.5996732, "ymax": 0.27020202 }
      },
      "atomic_grounding": [],
      "row": 0, "col": 1, "colspan": 1, "rowspan": 1
    }
    // ...
  ]
}

Grounding: Where Things Are

Every node below the root document carries a grounding object. The same shape appears on pages, blocks, and each atomic_grounding entry, so any grounding object is self-contained: you can lift it out of the tree and it still locates its content.

"grounding": {
  "page": 1,
  "range": { "start": 29, "end": 112 },
  "box": { "xmin": 0.08006536, "ymin": 0.11994949, "xmax": 0.91993464, "ymax": 0.18055556 }
}

Field	Description
`page`	The 1-indexed page number this content appears on. On a `page` node, the page’s own number.
`range`	The block’s extent in the top-level `markdown` string, as `{"start": n, "end": n}`. The `start` offset is inclusive and `end` is exclusive, in Unicode code points (see `metadata.range_units`).
`box`	The bounding box, as `{"xmin": n, "ymin": n, "xmax": n, "ymax": n}` in normalized page coordinates: each value is a fraction of the page’s width (`xmin`, `xmax`) or height (`ymin`, `ymax`), from 0 to 1, with at most 8 decimal places.
`confidence`	only: how certain the model is that it transcribed this content correctly, from 0 to 1. On a word entry, the word’s own score. On a block, table, or page, the lowest score among the words the model read inside it. Absent when the content was captioned rather than read, and never present on . See Word Confidence Scores.

Working with Boxes

Boxes are resolution-independent. To convert a box to pixels, multiply its x values by the width and its y values by the height of whatever rendering of the page you draw on. The same box lines up at any resolution because it scales with the dimensions you supply. For images with EXIF orientation metadata (such as phone photos), the API applies the orientation before parsing, so boxes align with the upright image as a viewer sees it. Use the upright dimensions when converting.

Python

box = block["grounding"]["box"]
left = box["xmin"] * image_width
top = box["ymin"] * image_height
right = box["xmax"] * image_width
bottom = box["ymax"] * image_height

Atomic Grounding

Grounding locates a whole block. Atomic grounding locates the content inside it: the atomic_grounding field breaks a block into its individual lines or words, with one grounding entry for each. Every entry has the same {page, range, box} shape as the block’s own grounding, so you can highlight single lines or words on the page, or slice them out of the Markdown. Every leaf block carries atomic_grounding. The document root, page nodes, and table nodes never carry it. A table’s cells carry it instead.

Line-Level vs. Word-Level Grounding

The granularity of atomic grounding depends on the parsing model family:

grounds at the line level: one entry per visual line.
grounds at the word level: one entry per word, each with a confidence score.

Entries by Block Type

Atomic grounding entries follow the block type and the model family. Any block the model cannot segment finer carries a single entry covering the block’s full range and box.

Block type	DPT-3 Pro	DPT-3 Fast
`text`, `marginalia`	One entry per visual line	One entry per word, with `confidence`
`table_cell`	No entries	One entry per word, with `confidence`
`figure`, `logo`, `card`, `scan_code`, `attestation`	One entry per transcribed segment	One entry per transcribed segment, without `confidence`

Range Boundaries

Atomic grounding entries are ordered, non-overlapping sub-ranges of the block’s own range. A line’s range stops before the newline that joins it to the next line. A word’s range includes the whitespace or newline that follows it.

When the Array Is Empty

An empty atomic_grounding array is expected in three cases:

A table_cell parsed with : cells have no line-level detail.
A block whose Markdown is suppressed with blocks.<type>.markdown=false.
A table_cell parsed with whose words cannot be located in the rendered cell text (for example, a character that is escaped in an HTML table). Those entries are dropped rather than risk ranges that point at the wrong characters.

Turn Off Atomic Grounding

To omit the field from every node in the response, set options.atomic_grounding to false. On , each node’s grounding keeps its rolled-up confidence even with atomic grounding off.

Word Confidence Scores (DPT-3 Fast)

scores every word it transcribes in text, tables, and marginalia. The confidence field on a word’s atomic grounding entry is a value between 0 and 1 for how certain the model is that it transcribed the word correctly. does not include confidence scores.

Where Confidence Score Appears

The confidence score appears at two levels of a response: on individual word entries, and rolled up onto node groundings.

Location	Confidence score
Word entries of `text`, `marginalia`, and `table_cell` blocks	The word’s own score.
Entries of `figure`, `logo`, `card`, `scan_code`, and `attestation` blocks	Never.
The `grounding` of a block, `table`, or `page`	The lowest score among the words the model read inside it. Absent when the content was captioned rather than read (a figure’s description, or a logo transcribed as a generic marker), so presence on visual blocks varies with their content.
The `document` root	Never.

In this trimmed text block, each word entry carries its own score, and the block’s grounding carries the lowest of them:

{
  "type": "text",
  "id": "text-0",
  "grounding": {
    "page": 1,
    "range": { "start": 52, "end": 212 },
    "box": { "xmin": 0.65844548, "ymin": 0.04807718, "xmax": 0.91910303, "ymax": 0.1076355 },
    "confidence": 0.846306622028
  },
  "atomic_grounding": [
    {
      "page": 1,
      "range": { "start": 52, "end": 65 },
      "box": { "xmin": 0.74462809, "ymin": 0.05284611, "xmax": 0.82378694, "ymax": 0.06078515 },
      "confidence": 0.999122440815
    },
    {
      "page": 1,
      "range": { "start": 134, "end": 136 },
      "box": { "xmin": 0.77741222, "ymin": 0.08043272, "xmax": 0.78065556, "ymax": 0.08701772 },
      "confidence": 0.846306622028
    }
  ]
}

How the Confidence Score Is Calculated

The confidence value is the lowest per-character score in the word: a single uncertain character lowers the score for the whole word. The same weakest-link rule rolls the scores up the tree. A block or table cell carries the lowest score among its words, a table the lowest among its cells, and a page the lowest among its blocks.

Handle Low-Confidence Words

Use the confidence score to route uncertain transcriptions to review instead of trusting every one equally, or to re-parse low-confidence documents with .

Look Up Blocks by ID

To look up blocks by id instead of walking the tree, flatten it into a map once:

Python

def iter_blocks(node):
    for child in node.get("children") or []:
        if child.get("id"):
            yield child
        yield from iter_blocks(child)

blocks_by_id = {b["id"]: b for b in iter_blocks(response["structure"])}

Slice the Markdown

Any grounding range turns into text with one slice: index the top-level markdown string with the range’s start and end offsets. The same slice works for a block’s grounding.range and for a single line or word from its atomic_grounding, so you can pull one table out of a long document or quote the exact words behind a value. Offsets count Unicode code points, as declared by metadata.range_units. To skip slicing entirely, set options.inline_markdown to true and each node carries its own markdown field instead. Slice a block’s range like this:

r = block["grounding"]["range"]
block_markdown = response["markdown"][r["start"]:r["end"]]

// Slice code points, not the string: JavaScript indexes strings by
// UTF-16 code units, which drift from the code-point offsets when the
// Markdown contains emoji or some CJK characters.
const codePoints = Array.from(response.markdown);
const { start, end } = block.grounding.range;
const blockMarkdown = codePoints.slice(start, end).join("");

Metadata

The metadata field describes the job.

Field	Description
`job_id`	A unique, server-generated identifier for this parse job. Useful for tracking a document across a workflow (for example, parse to extract) and for support requests.
`model_version`	The exact model snapshot used (for example, `dpt-3-pro-20260710`).
`page_count`	Total number of pages in the source document. Includes pages filtered out by `options.pages`; the pages actually returned are in `structure.children`.
`output_markdown_chars`	Number of Unicode code points in the returned `markdown` string.
`range_units`	The units of every `range` offset in the response. Always `"unicode_codepoints"`. Declared explicitly because some languages index strings differently; see Slice the Markdown.
`openapi_spec`	The URL of the OpenAPI spec that describes this API. Use it for inspection or client generation.
`failed_pages`	An array of 1-indexed page numbers that failed to parse. Empty on success. Also reflected inline in `structure.children` with `status: "failed"` and a `reason`. See Troubleshoot Parsing.
`duration_ms`	Total processing time in milliseconds.
`billing`	Billing details: `service_tier` is the service tier the request ran on (`standard` or `priority`; synchronous requests always report `priority`), and `total_credits` is the credits consumed (`0` if none). See Credit Consumption.

A complete metadata block could look like this:

{
  "job_id": "parse-01k04g2b8xv9q3m5n7r2sd4tfe",
  "model_version": "dpt-3-pro-20260710",
  "page_count": 1,
  "output_markdown_chars": 3765,
  "range_units": "unicode_codepoints",
  "openapi_spec": "https://api.ade.landing.ai/openapi.json",
  "failed_pages": [],
  "duration_ms": 17266,
  "billing": {
    "service_tier": "priority",
    "total_credits": 2.9
  }
}

Get Started

Client Libraries

Parsing

Extraction

General

Security

Administration

Pricing & Credits

Parse API Response

The Response Shape

Markdown

Figures

Attestations

Structure: Pages and Blocks

Common Block Fields

Page Fields

Block Types

Tables and Cells

Grounding: Where Things Are

Working with Boxes

Atomic Grounding

Line-Level vs. Word-Level Grounding

Entries by Block Type

Range Boundaries

When the Array Is Empty

Turn Off Atomic Grounding

Word Confidence Scores (DPT-3 Fast)

Where Confidence Score Appears

How the Confidence Score Is Calculated

Handle Low-Confidence Words

Look Up Blocks by ID

Slice the Markdown

Metadata

​The Response Shape

​Markdown

​Figures

​Attestations

​Structure: Pages and Blocks

​Common Block Fields

​Page Fields

​Block Types

​Tables and Cells

​Grounding: Where Things Are

​Working with Boxes

​Atomic Grounding

​Line-Level vs. Word-Level Grounding

​Entries by Block Type

​Range Boundaries

​When the Array Is Empty

​Turn Off Atomic Grounding

​Word Confidence Scores (DPT-3 Fast)

​Where Confidence Score Appears

​How the Confidence Score Is Calculated

​Handle Low-Confidence Words

​Look Up Blocks by ID

​Slice the Markdown

​Metadata

The Response Shape

Markdown

Figures

Attestations

Structure: Pages and Blocks

Common Block Fields

Page Fields

Block Types

Tables and Cells

Grounding: Where Things Are

Working with Boxes

Atomic Grounding

Line-Level vs. Word-Level Grounding

Entries by Block Type

Range Boundaries

When the Array Is Empty

Turn Off Atomic Grounding

Word Confidence Scores (DPT-3 Fast)

Where Confidence Score Appears

How the Confidence Score Is Calculated

Handle Low-Confidence Words

Look Up Blocks by ID

Slice the Markdown

Metadata