> ## Documentation Index > Fetch the complete documentation index at: https://docs.landing.ai/llms.txt > Use this file to discover all available pages before exploring further. # Parse API Response > Read the Parse response: reading-order Markdown, document structure, per-block grounding, and metadata. export const dpt3pro = 'DPT-3 Pro'; export const dpt3 = 'DPT-3'; export const parseDpt3 = 'Parse'; export const ade = 'Agentic Document Extraction'; 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`](#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. Carries types, ids, and Markdown spans only (no spatial data). | | [`grounding`](#grounding-where-things-are) | 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](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. 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 `` and `` tags. | 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 v2 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: `
` wraps the figure's transcribed text and one or more generated `...` blocks. See [Figure and Attestation Labels](#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). | ### 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: `
...
`. Inside the element, the figure's visible text is transcribed, and generated descriptions of the visual content appear in `...` blocks. A `CHART` figure also transcribes the chart's data as an HTML `
`. 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`) | `
Bar chart of quarterly revenue
` | | 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`](#grounding-where-things-are). ### Common Block Fields Every node in the structure tree shares the same base shape: | Field | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | The node type. See [block types](#block-types) below. | | `id` | A unique block identifier within the document. Matches the block's node in the [`grounding`](#grounding-where-things-are) 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](./parse-input#request-options). 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 {parseDpt3} 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. | ```json theme={null} { "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`](#structure-pages-and-blocks): 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 `id`s 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`: ```json theme={null} { "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 Python theme={null} 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: ```json theme={null} { "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](./parse-input#request-options) (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: ```python theme={null} 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 Python theme={null} 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 JavaScript theme={null} 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](./parse-troubleshoot#status-206-partial-content). | | `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](./credit-consumption). | A complete `metadata` block looks like this: ```json theme={null} { "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 } } ```