> ## 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 span 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 span grounding for each value.
* `markdown`: the input Markdown, echoed back unchanged. All `spans` offsets index into this string.
* [`metadata`](#request-metadata-metadata): request information such as the job ID, model version, and duration.

## 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, spans}` object:

* `value`: the extracted value, matching the corresponding leaf in `extraction`.
* `spans`: an array of `[start, end)` Unicode code point offsets that locate the value in the input Markdown. See [Grounding with Spans](#grounding-with-spans).

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

### Grounding with Spans

Every extracted value is grounded: its `spans` tell you where the value came from in the input Markdown.

For each leaf value in `extraction_metadata`, `spans` is an array of `[start, end)` Unicode code point offsets into the Markdown string you submitted, 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 `spans` array follows these rules:

* Each pair marks a range of characters, where `start` is inclusive and `end` is exclusive.
* The `spans` array can contain more than one pair, 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 `spans` are `null`.

### Slice the Markdown with Python

A value's `spans` 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 span, join the slices:

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

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

```javascript JavaScript theme={null}
const codePoints = Array.from(response.markdown);
const text = spans.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.                                                                                                                                                       |
| `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).                                           |
| `credit_usage` | number         | Credits consumed by this request (`0` if none were consumed). See [Credit Consumption](./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` matches `credit_usage`. |

## Example Response

This response extracts a `revenue` value and a `summary` from a one-page financial report. The `revenue` value is grounded: its span `[164, 169]` 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 `spans` 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",
      "spans": [[164, 169]]
    },
    "summary": {
      "value": null,
      "spans": null
    }
  },
  "metadata": {
    "job_id": "d3kpfw9bf0ez7e501an5qqe8z",
    "doc_id": "cmpkfw4bf0ez7e501an5qqe8y",
    "version": "extract-20260710",
    "duration_ms": 843,
    "credit_usage": 0.4,
    "billing": {
      "service_tier": "priority",
      "total_credits": 0.4
    }
  }
}
```