Skip to main content
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 span grounding for each value.
  • markdown: the input Markdown, echoed back unchanged. All spans offsets index into this string.
  • 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: 
{
  "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.
{
  "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 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
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
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:
FieldTypeDescription
job_idstringThe unique identifier for this request.
versionstringThe resolved model version, such as extract-20260710.
duration_msnumberThe end-to-end request duration in milliseconds.
doc_idstring | nullThe 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_usagenumberCredits consumed by this request (0 if none were consumed). See Credit Consumption.
billingobjectBilling 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. 
{
  "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
    }
  }
}