Extract API Response

A successful extraction returns a JSON object with the extracted values, per-field metadata, and request metadata.

Response Structure

The response contains these top-level fields:

extraction: the extracted values, structured to match your schema.
extraction_metadata: per-field metadata with the range grounding for each value.
markdown: the input Markdown, echoed back unchanged. All ranges offsets index into this string.
metadata: request information such as the job ID, model version, and duration.
warnings: non-fatal warnings emitted during extraction. Empty when the extraction is clean.
schema_violation_error: set when options.strict is false and the schema contained fields the model could not extract; the extraction is partial. See Status 206.

When warnings or schema_violation_error is set, a synchronous request returns HTTP 206 instead of 200. An Extract Jobs poll always returns HTTP 200, with these fields inside result.

Extracted Values (`extraction`)

The extraction field contains the values extracted from the document, structured to match your schema exactly. When a value cannot be found in the source, it is returned as null. For a schema that requests a revenue field and a summary field, extraction returns:

{
  "revenue": "$4.2M",
  "summary": "Strong Q1 driven by 12% YoY revenue growth and enterprise adoption"
}

Per-Field Metadata (`extraction_metadata`)

The extraction_metadata field mirrors the structure of extraction, with each leaf value replaced by a {value, ranges} object:

value: the extracted value, matching the corresponding leaf in extraction.
ranges: an array of {"start": n, "end": n} objects that locate the value in the input Markdown. See Grounding with Ranges.

{
  "revenue": {
    "value": "$4.2M",
    "ranges": [{ "start": 164, "end": 169 }]
  },
  "summary": {
    "value": "Strong Q1 driven by 12% YoY revenue growth and enterprise adoption",
    "ranges": null
  }
}

Grounding with Ranges

A value copied from the input is grounded: its ranges tell you where it came from in the input Markdown. For each leaf value in extraction_metadata, ranges is an array of {"start": n, "end": n} objects. Each marks a [start, end) slice of the Markdown string you submitted, in Unicode code point offsets, so you can map any value back to its exact location in the text. For bounding boxes on the page (visual grounding), pass the response’s extraction_metadata and the parse’s structure to the Ground API, which maps each field to the blocks it came from, with page numbers and coordinates. Each entry in the ranges array follows these rules:

Each object marks a range of characters, where start is inclusive and end is exclusive.
The ranges array can contain more than one object, because a single value can appear in more than one place in the document.
When a value is synthesized rather than copied from the source, ranges is null. The value still carries the extracted value.

Slice the Markdown

A value’s ranges index into the returned markdown string, which echoes your input back unchanged, so you can quote the exact source text behind an extracted value. Offsets count Unicode code points, as declared by metadata.range_units. A value can have more than one range. Join the slices to reassemble its text:

text = "".join(response["markdown"][r["start"]:r["end"]] for r in ranges)

// 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 text = ranges.map(({ start, end }) => codePoints.slice(start, end).join("")).join("");

Request Metadata (`metadata`)

The metadata field provides information about the request:

Field	Type	Description
`job_id`	string	The unique identifier for this request.
`model_version`	string	The resolved model version, such as `extract-20260819`.
`duration_ms`	number	The end-to-end request duration in milliseconds.
`doc_id`	string \| null	The ID of the originating parse job. Present only when the input Markdown contains a `<!-- doc_id=<id> -->` comment (embedded by the Parse API).
`range_units`	string	The units of every `ranges` offset in the response. Always `"unicode_codepoints"`. Declared explicitly because some languages index strings differently; see Slice the Markdown.
`openapi_spec`	string	The URL of the OpenAPI spec that describes this API. Use it for inspection or client generation.
`input_markdown_chars`	number	The number of Unicode code points in the Markdown you submitted. This is the input basis of the credit charge.
`output_extraction_chars`	number	The number of characters in the serialized extraction output. This is the output basis of the credit charge. Together with `input_markdown_chars`, it lets you verify the credit consumption from the response. See Credit Consumption.
`billing`	object	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.

Example Response

This response extracts a revenue value and a summary from a one-page financial report. The revenue value is grounded: its range covers the characters $4.2M in the input Markdown. The summary value is synthesized from the document as a whole rather than copied from one location, so its ranges is null. Its value still carries the summary text.

{
  "extraction": {
    "revenue": "$4.2M",
    "summary": "Strong Q1 driven by 12% YoY revenue growth and enterprise adoption"
  },
  "extraction_metadata": {
    "revenue": {
      "value": "$4.2M",
      "ranges": [{ "start": 164, "end": 169 }]
    },
    "summary": {
      "value": "Strong Q1 driven by 12% YoY revenue growth and enterprise adoption",
      "ranges": null
    }
  },
  "metadata": {
    "job_id": "extract-01k04h6t8rw2xq9v3m5npbsd4f",
    "doc_id": "parse-01k04g2b8xv9q3m5n7r2sd4tfe",
    "model_version": "extract-20260819",
    "range_units": "unicode_codepoints",
    "openapi_spec": "https://api.ade.landing.ai/openapi.json",
    "duration_ms": 843,
    "input_markdown_chars": 396,
    "output_extraction_chars": 100,
    "billing": {
      "service_tier": "priority",
      "total_credits": 0.4
    }
  }
}

Get Started

Client Libraries

Parsing

Extraction

Grounding

General

Security

Administration

Pricing & Credits

Extract API Response

Response Structure

Extracted Values (`extraction`)

Per-Field Metadata (`extraction_metadata`)

Grounding with Ranges

Slice the Markdown

Request Metadata (`metadata`)

Example Response

​Response Structure

​Extracted Values (extraction)

​Per-Field Metadata (extraction_metadata)

​Grounding with Ranges

​Slice the Markdown

​Request Metadata (metadata)

​Example Response

Response Structure

Extracted Values (`extraction`)

Per-Field Metadata (`extraction_metadata`)

Grounding with Ranges

Slice the Markdown

Request Metadata (`metadata`)

Example Response