> ## 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 with 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 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). 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 [Figures](#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](#attestations). | ### Figures A figure is wrapped in an HTML-style element whose `type` attribute is the classification 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 `
`. The figure type labels are `CHART`, `FLOWCHART`, `DIAGRAM`, `ILLUSTRATION`, and `PHOTOGRAPH`, with `FIGURE` as the fallback. **Example** A bar chart could render like this: ```html theme={null}
Bar chart of quarterly revenue
``` ### 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`](#grounding-where-things-are) 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](#block-types) below. | | `id` | A semantic block identifier, unique within the document, in the format `-`. 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](#grounding-where-things-are). | | `atomic_grounding` | Finer-grained grounding segments within the block. Present only on leaf blocks (every type except `table`). See [Atomic Grounding](#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`](./parse-input#request-options) 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 {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 `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. ```json theme={null} { "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. ```json theme={null} "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`](#metadata)). | | `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 Python theme={null} 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..markdown=false`](./parse-input#request-options) 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`](./parse-input#request-options) 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: ```json theme={null} { "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 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) 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 Python theme={null} r = block["grounding"]["range"] block_markdown = response["markdown"][r["start"]:r["end"]] ``` To skip slicing entirely, set [`options.inline_markdown`](./parse-input#request-options) 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 JavaScript theme={null} 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](#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](./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 could look like this: ```json theme={null} { "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 } } ```