> ## 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.

# Extract API Response

> Read the Extract response: extracted values, per-field range grounding, and metadata.

export const dpt3 = 'DPT-3';

export const extractDpt3 = 'Extract';

export const parseDpt3 = 'Parse';

export const ade = 'Agentic Document Extraction';

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`](#extracted-values-extraction): the extracted values, structured to match your schema.
* [`extraction_metadata`](#per-field-metadata-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-metadata-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](./extract-troubleshoot#status-206-partial-success).

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:

```json theme={null}
{
  "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](#grounding-with-ranges).

```json theme={null}
{
  "revenue": {
    "value": "$4.2M",
    "ranges": [{ "start": 164, "end": 169 }]
  },
  "summary": {
    "value": null,
    "ranges": null
  }
}
```

### Grounding with Ranges

Every extracted value is grounded: its `ranges` tell you where the value 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), use the grounding from the [Parse v2 API](https://docs.landing.ai/api-reference/parse/ade-parse) instead, which reports coordinates for each block.

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, both `value` and `ranges` are `null`.

### Slice the Markdown with Python

A value's `ranges` index into the returned `markdown` string, which echoes your input back unchanged. Python string indexing is code-point based, so index it directly. Because a value can have more than one range, join the slices:

```python Python theme={null}
text = "".join(response["markdown"][r["start"]:r["end"]] for r in ranges)
```

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

```javascript JavaScript theme={null}
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-20260710`.                                                                                                                                                                                                                 |
| `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 v2 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 with JavaScript](#slice-the-markdown-with-javascript).                                 |
| `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](./credit-consumption#extract). |
| `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](./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 `value` and `ranges` are `null`.

```json theme={null}
{
  "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": null,
      "ranges": null
    }
  },
  "metadata": {
    "job_id": "extract-01k04h6t8rw2xq9v3m5npbsd4f",
    "doc_id": "parse-01k04g2b8xv9q3m5n7r2sd4tfe",
    "model_version": "extract-20260710",
    "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
    }
  }
}
```