Parse API Response

A successful parse returns a JSON object with the reading-order Markdown, the document structure, 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. Carries types, ids, and Markdown spans only (no spatial data).
`grounding`	A tree that mirrors `structure` and carries the spatial data: each block’s bounding box and finer-grained parts.

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. All span offsets elsewhere in the response point into this string as Unicode code point indices. 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 Figure and Attestation Labels.
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	A bracketed classification label on its own line, followed by the transcribed text: `[TYPE]`, then the mark and any printed text as plain prose. See Figure and Attestation Labels.

Figure and Attestation Labels

Figures and attestations carry a classification label that downstream consumers can branch on without re-running detection. A figure is wrapped in an HTML-style element whose type attribute is the 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>. An attestation emits a bracketed [TYPE] label on its own line, followed by the transcribed text of the mark and any surrounding printed text as plain prose. A mark that cannot be read is transcribed as [ILLEGIBLE_SIGNATURE].

Block	Labels	Example
Figure	`CHART`, `FLOWCHART`, `DIAGRAM`, `ILLUSTRATION`, `PHOTOGRAPH` (fallback `FIGURE`)	`<figure type="CHART"><description>Bar chart of quarterly revenue</description></figure>`
Attestation	`SIGNED`, `E-SIGNED`, `STAMPED`, `SEALED` (printed text has no label)	`[SIGNED]` followed by `J. Doe` on the next line

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. The tree carries types, ids, and Markdown spans. Spatial information lives in grounding.

Common Block Fields

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

Field	Description
`type`	The node type. See block types below.
`id`	A unique block identifier within the document. Matches the block’s node in the `grounding` tree. Treat as opaque (current model versions emit stringified monotonically-increasing integers, but the shape is not part of the contract).
`span`	A two-block array `[start, end)` giving the Unicode code point offsets in the global `markdown` string covered by this node.
`children`	Child blocks. Present on `document`, `page`, and `table`.

Page Fields

page nodes have additional fields describing the source page:

Field	Description
`page`	The 0-indexed page number in the source document.
`width`, `height`	Page dimensions, in pixels. `null` for failed pages.
`dpi`	For PDF pages, the DPI used to scale the page’s coordinates to pixels (`pixels = PDF points × dpi / 72`), controlled by the `dpi` option. Present only for pages that originated from a PDF; absent for image inputs (already in pixels) and for failed pages.
`status`	`"ok"` if the page was parsed successfully, or `"failed"`.
`reason`	Failure reason. Present only when `status` is `"failed"`.
`span`	Markdown range covering the page’s content. Zero-length `[n, n]` 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 span, and a children array of table_cell blocks in row-major order. Every cell uses the table_cell type, including cells in header rows; there is no separate header-cell type. 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.

{
  "type": "table",
  "id": "25",
  "span": [1793, 2576],
  "children": [
    { "type": "table_cell", "id": "26", "span": [1821, 1831], "row": 0, "col": 0, "colspan": 1, "rowspan": 2 },
    { "type": "table_cell", "id": "28", "span": [1884, 1902], "row": 0, "col": 2, "colspan": 2, "rowspan": 1 },
    { "type": "table_cell", "id": "32", "span": [2028, 2036], "row": 1, "col": 2, "colspan": 1, "rowspan": 1 },
    { "type": "table_cell", "id": "33", "span": [2045, 2052], "row": 1, "col": 3, "colspan": 1, "rowspan": 1 }
    // ...
  ]
}

Grounding: Where Things Are

The top-level grounding field is a tree that mirrors structure: a document node whose children are pages, and each page’s children are the blocks on that page, in the same order and with the same ids as in structure. Where structure carries the document hierarchy, grounding carries the spatial data: each block node repeats its id and span and adds a bounding box and finer-grained parts. A table node nests its cells’ grounding as children:

{
  "type": "document",
  "children": [
    {
      "type": "page",
      "page": 0,
      "span": [0, 354],
      "children": [
        {
          "type": "text",
          "id": "2",
          "span": [29, 112],
          "box": [49, 95, 563, 143],
          "parts": [
            { "span": [29, 74],  "box": [49, 95,  563, 119] },
            { "span": [75, 112], "box": [49, 119, 355, 143] }
          ]
        },
        {
          "type": "table",
          "id": "3",
          "span": [114, 212],
          "box": [49, 160, 563, 360],
          "parts": [],
          "children": [
            { "type": "table_cell", "id": "4", "span": [142, 152], "box": [49, 160, 306, 210], "parts": [] }
            // ...
          ]
        }
      ]
    }
  ]
}

Page Nodes

Field	Description
`page`	The 0-indexed page number in the source document. Matches the page’s `page` in the `structure` tree.
`span`	Markdown range covering the page’s content. Zero-length `[n, n]` for failed pages.
`children`	Grounding nodes for the page’s blocks, in reading order. Empty for failed pages.

Block Grounding Fields

Field	Description
`type`	The block type. Matches the same block’s `type` in the `structure` tree.
`id`	The block’s unique identifier. Matches the same block’s `id` in the `structure` tree.
`span`	A two-block array `[start, end)` giving the Unicode code point offsets in the global `markdown` string covered by the full block. Matches the `span` on the same block in the `structure` tree.
`box`	A four-block array `[left, top, right, bottom]` giving the block’s bounding box on the source page, in pixels.
`parts`	Finer-grained grounding segments. Each entry has the same `span` and `box` shape as the block-level fields.
`children`	On `table` nodes only: grounding for the table’s cells (`table_cell` nodes), mirroring the table’s `children` in the `structure` tree.

A block’s page number comes from its enclosing page node; block nodes do not carry a page field of their own.

Look Up Grounding by Block ID

Because grounding mirrors structure node for node, you can walk the two trees in lockstep. If your code looks up grounding by block id instead, flatten the tree 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)

grounding_by_id = {g["id"]: g for g in iter_blocks(response["grounding"])}

Parts

The parts array gives line-level (or finer) detail:

For text and marginalia, you get one entry per visual line.
For figure, logo, card, scan_code, and attestation, you get one entry per transcribed line within the block.
For table and table_cell, parts is an empty array [].
Segment spans are contiguous sub-ranges of the block’s span.

Example: Multi-Line Paragraph

A paragraph that wraps across two visual lines produces one block node with two parts. The block-level box covers both lines:

{
  "type": "text",
  "id": "2",
  "span": [29, 112],
  "box": [49, 95, 563, 143],
  "parts": [
    { "span": [29, 74],  "box": [49, 95,  563, 119] },
    { "span": [75, 112], "box": [49, 119, 355, 143] }
  ]
}

Working with Boxes

Boxes use integer pixel coordinates. For PDFs, the pixel resolution is set by the dpi option (default 200); for images, coordinates are pixels relative to the original upload. Because coordinates and the page’s width and height share the same pixel scale, you can normalize a box to page-relative coordinates without needing the DPI:

left, top, right, bottom = entry["box"]
normalized = (
    left / page["width"],
    top / page["height"],
    right / page["width"],
    bottom / page["height"],
)

Slice the Markdown with Python

To get a block’s text, index the markdown string with its span offsets. Python string indexing is code-point based, so the offsets map directly onto the string. When a block has multiple parts, slice each part’s span separately:

Python

start, end = entry["span"]
block_markdown = response["markdown"][start:end]

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 spans 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 spans:

JavaScript

const codePoints = Array.from(response.markdown);
const [start, end] = entry.span;
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`.
`markdown_chars`	Number of Unicode code points in the returned `markdown` string.
`failed_pages`	An array of 0-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 looks like this:

{
  "job_id": "parse-api-89b2c54c78dd-doc",
  "model_version": "dpt-3-pro-20260710",
  "page_count": 1,
  "markdown_chars": 3765,
  "failed_pages": [],
  "duration_ms": 17266,
  "billing": {
    "service_tier": "priority",
    "total_credits": 2.9
  }
}

​The Response Shape

​Markdown

​Figure and Attestation Labels

​Structure: Pages and Blocks

​Common Block Fields

​Page Fields

​Block Types

​Tables and Cells

​Grounding: Where Things Are

​Page Nodes

​Block Grounding Fields

​Look Up Grounding by Block ID

​Parts

​Example: Multi-Line Paragraph

​Working with Boxes

​Slice the Markdown with Python

​Slice the Markdown with JavaScript

​Metadata