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. Math formulas are transcribed as LaTeX, wrapped in $...$ for inline math or $$...$$ for display math, matching the original layout. Superscript and subscript text that is not part of a math formula is wrapped in <sup> and <sub> tags.

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; its cells are leaf blocks whose atomic_grounding is always an empty array. A cell’s range points to its own content in the Markdown, so an empty cell has a zero-length range.

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

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

Leaf blocks (every type except table) also carry atomic_grounding: an array of grounding objects, each with the same {page, range, box} shape as the block’s own grounding, one entry per finer-grained segment.

For text and marginalia, there is one entry per visual line, so you can highlight or extract content at the line level. Line ranges are ordered, non-overlapping sub-ranges of the block’s range; consecutive lines are separated by the newline that joins them in the Markdown.
For figure, logo, card, scan_code, and attestation, there is one entry per transcribed segment the model can localize, or a single entry covering the block’s full range and box when no finer segmentation exists.
For table_cell, the array is always empty; a cell has no finer granularity than itself.
Blocks suppressed with blocks.<type>.markdown=false also return an empty array.
The field never appears on document, page, or table nodes.

To omit the field entirely from every node, set options.atomic_grounding to false.

Example: Multi-Line Paragraph

A paragraph that wraps across two visual lines produces one text block with two atomic_grounding entries. The block-level box covers both lines; each atomic entry covers one line:

{
  "type": "text",
  "id": "text-1",
  "grounding": {
    "page": 1,
    "range": { "start": 29, "end": 112 },
    "box": { "xmin": 0.08006536, "ymin": 0.11994949, "xmax": 0.91993464, "ymax": 0.18055556 }
  },
  "atomic_grounding": [
    {
      "page": 1,
      "range": { "start": 29, "end": 74 },
      "box": { "xmin": 0.08006536, "ymin": 0.11994949, "xmax": 0.91993464, "ymax": 0.15025253 }
    },
    {
      "page": 1,
      "range": { "start": 75, "end": 112 },
      "box": { "xmin": 0.08006536, "ymin": 0.15025253, "xmax": 0.58006536, "ymax": 0.18055556 }
    }
  ]
}

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 with Python

To get a block’s text, index the markdown string with its range offsets. Python string indexing is code-point based, so the offsets map directly onto the string:

Python

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

To skip slicing entirely, set options.inline_markdown to true; each node then carries its own markdown field.

Slice the Markdown with JavaScript

In JavaScript, slice a code-point array so the offsets stay aligned. JavaScript strings index by UTF-16 code units, so building the array with Array.from() first keeps ranges correct even when the Markdown contains characters outside the Basic Multilingual Plane, such as emoji or some CJK characters. Build the array once and reuse it across ranges:

JavaScript

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 with JavaScript.
`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

Example: Multi-Line Paragraph

Look Up Blocks by ID

Slice the Markdown with Python

Slice the Markdown with JavaScript

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

​Example: Multi-Line Paragraph

​Look Up Blocks by ID

​Slice the Markdown with Python

​Slice the Markdown with JavaScript

​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

Example: Multi-Line Paragraph

Look Up Blocks by ID

Slice the Markdown with Python

Slice the Markdown with JavaScript

Metadata