Structured Extraction

Extract specific fields from documents by providing a JSON schema. Marker parses the document and fills in your schema with extracted values. Before you begin, make sure you have:

A Datalab account with an API key (new accounts include $5 in free credits)
Python 3.10+ installed
The Datalab SDK: pip install datalab-python-sdk
Your DATALAB_API_KEY environment variable set

EU requests return a signed result_url; the REST examples below download it before reading the output. See Regional Result Downloads, including the Python SDK 0.5.0 limitation.

Building for production? Use Pipelines to chain processors, version your configuration, and deploy with a single API call.

Quick Start

import json
from datalab_sdk import DatalabClient, ExtractOptions

client = DatalabClient()

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string", "description": "Invoice ID or number"},
        "total_amount": {"type": "number", "description": "Total amount due"},
        "vendor_name": {"type": "string", "description": "Company or vendor name"}
    },
    "required": ["invoice_number", "total_amount"]
}

options = ExtractOptions(
    page_schema=json.dumps(schema),
    mode="balanced"
)

result = client.extract("invoice.pdf", options=options)
extracted = json.loads(result.extraction_schema_json)
print(f"Invoice: {extracted['invoice_number']}")
print(f"Total: ${extracted['total_amount']}")

curl -X POST https://www.datalab.to/api/v1/extract \
  -H "X-API-Key: $DATALAB_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "mode=balanced" \
  -F 'page_schema={"type":"object","properties":{"invoice_number":{"type":"string","description":"Invoice ID"},"total_amount":{"type":"number","description":"Total due"}}}'

# Poll request_check_url from response until status is "complete"

import requests, json, time, os

headers = {"X-API-Key": os.getenv("DATALAB_API_KEY")}

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string", "description": "Invoice ID"},
        "total_amount": {"type": "number", "description": "Total due"}
    }
}

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        "https://www.datalab.to/api/v1/extract",
        files={"file": ("invoice.pdf", f, "application/pdf")},
        data={"page_schema": json.dumps(schema), "mode": "balanced"},
        headers=headers
    )

check_url = response.json()["request_check_url"]

while True:
    result = requests.get(check_url, headers=headers).json()
    if result.get("success") is False or result.get("status") == "failed":
        raise RuntimeError(result.get("error") or "Document processing failed")
    if result["status"] == "complete":
        if result.get("result_url"):
            download = requests.get(result["result_url"], timeout=60)
            download.raise_for_status()
            result = {**download.json(), **{k: v for k, v in result.items() if v is not None}}
        if result.get("success") is False:
            raise RuntimeError(result.get("error") or "Document processing failed")
        extracted = result["extraction_schema_json"]
        if isinstance(extracted, str):
            extracted = json.loads(extracted)
        print(extracted)
        break
    time.sleep(2)

Extraction Modes

The extraction_mode form parameter controls how extraction runs. This is separate from mode, which controls document parsing quality.

Mode	Description	Base extraction rate	Latency
turbo	Image-only extraction without OCR, citations, verification, or confidence scores. Returns extracted JSON without parsed document output.	$6 / 1K pages	Lowest
fast	Extraction with per-field citations	$6 / 1K pages	Lowest
balanced (default)	Extraction with independent verification, per-field reasoning, and citations	$15 / 1K pages	Moderate
accurate	Balanced extraction plus deeper completeness auditing and a stronger model for hard cases	$20 / 1K pages	Slower

Fast, balanced, and accurate modes return per-field citations. Balanced and accurate modes also return _meta fields with extraction_status, reasoning, and verification results. Turbo requires the source file and cannot reuse a checkpoint. These are base extraction rates. Parsing is billed separately when it runs, and complex balanced or accurate requests can incur usage-based charges. See Billing and pricing for your applicable rates. When mode is omitted from a REST request, balanced and accurate extraction use accurate parsing; fast uses fast parsing. An explicit mode overrides this choice. Turbo skips parsing.

balanced is the default. Teams that made an extraction request in the 30 days before June 4, 2026 default to fast instead. Pass extraction_mode explicitly to override the default in either case.

import json
from datalab_sdk import DatalabClient, ExtractOptions

client = DatalabClient()
schema = {"type": "object", "properties": {"invoice_number": {"type": "string"}}}
options = ExtractOptions(page_schema=json.dumps(schema), extraction_mode="accurate", mode="accurate")
result = client.extract("invoice.pdf", options=options)
print(result.extraction_schema_json)

curl -X POST https://www.datalab.to/api/v1/extract \
  -H "X-API-Key: $DATALAB_API_KEY" \
  -F "file=@invoice.pdf" \
  -F 'page_schema={"type":"object","properties":{"invoice_number":{"type":"string"}}}' \
  -F "extraction_mode=accurate" \
  -F "mode=accurate"

# Poll request_check_url from the response until status is complete or failed.

import json
import os
import time
import requests

headers = {"X-API-Key": os.environ["DATALAB_API_KEY"]}
schema = {"type": "object", "properties": {"invoice_number": {"type": "string"}}}
with open("invoice.pdf", "rb") as file:
    response = requests.post(
        "https://www.datalab.to/api/v1/extract",
        headers=headers,
        files={"file": ("invoice.pdf", file, "application/pdf")},
        data={"page_schema": json.dumps(schema), "extraction_mode": "accurate", "mode": "accurate"},
    )
response.raise_for_status()
check_url = response.json()["request_check_url"]
while True:
    response = requests.get(check_url, headers=headers)
    response.raise_for_status()
    result = response.json()
    if result.get("success") is False or result.get("status") == "failed":
        raise RuntimeError(result.get("error", "Extraction failed"))
    if result.get("status") == "complete":
        if result.get("result_url"):
            download = requests.get(result["result_url"], timeout=60)
            download.raise_for_status()
            result = {**download.json(), **{k: v for k, v in result.items() if v is not None}}
        if result.get("success") is False:
            raise RuntimeError(result.get("error") or "Document processing failed")
        print(result["extraction_schema_json"])
        break
    time.sleep(2)

See Balanced and Accurate Extraction Modes for verification metadata and examples.

Schema Format

Use JSON Schema format to define what you want to extract:

{
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Describe what this field contains"
    },
    "numeric_field": {
      "type": "number",
      "description": "A numeric value"
    },
    "list_field": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nested_field": {"type": "string"}
        }
      }
    }
  },
  "required": ["field_name"]
}

Tips for Better Extraction

Use descriptive field names - invoice_number is clearer than id
Add descriptions - The description field helps the model understand context
Specify types correctly - Use number for numeric values, string for text
Use arrays for repeating data - Line items, table rows, etc.

Common schema pitfalls:

Using vague field names like data or info — be specific (e.g., invoice_number, total_amount)
Forgetting description fields — these help the model understand what to extract
Setting type: "string" for numeric values — use type: "number" for amounts, quantities, etc.
Deeply nested schemas — keep schemas as flat as possible for better extraction accuracy

Response

The extracted data is returned in extraction_schema_json:

{
  "status": "complete",
  "success": true,
  "json": {...},
  "extraction_schema_json": "{\"invoice_number\": \"INV-2024-001\", \"total_amount\": 1500.00, ...}",
  "page_count": 2
}

Citation Tracking

Each extracted field includes citations to the source blocks:

{
  "invoice_number": "INV-2024-001",
  "invoice_number_citations": ["block_123", "block_124"],
  "total_amount": 1500.00,
  "total_amount_citations": ["block_456"]
}

Use these block IDs with the json output to trace extracted values back to the source document.

Schema Examples

Financial Document

schema = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string", "description": "Company name"},
        "fiscal_year": {"type": "string", "description": "Fiscal year"},
        "total_revenue": {"type": "number", "description": "Total revenue in dollars"},
        "net_income": {"type": "number", "description": "Net income in dollars"},
        "eps": {"type": "number", "description": "Earnings per share"}
    }
}

Scientific Paper

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string", "description": "Paper title"},
        "authors": {
            "type": "array",
            "items": {"type": "string"},
            "description": "List of author names"
        },
        "abstract": {"type": "string", "description": "Paper abstract"},
        "keywords": {
            "type": "array",
            "items": {"type": "string"},
            "description": "Keywords or tags"
        }
    }
}

Contract

schema = {
    "type": "object",
    "properties": {
        "parties": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"}
                }
            }
        },
        "effective_date": {"type": "string", "description": "Contract start date"},
        "termination_date": {"type": "string", "description": "Contract end date"},
        "total_value": {"type": "number", "description": "Total contract value"}
    }
}

Using Checkpoints

If you already converted a document with save_checkpoint=True using the Convert API, pass the checkpoint_id to ExtractOptions to skip re-parsing. Send the checkpoint without a file or file URL. Turbo extraction requires source images and cannot reuse checkpoints.

from datalab_sdk import DatalabClient, ConvertOptions, ExtractOptions
import json

client = DatalabClient()

# Step 1: Convert and save checkpoint
convert_result = client.convert("invoice.pdf", options=ConvertOptions(save_checkpoint=True))
checkpoint_id = convert_result.checkpoint_id

# Step 2: Extract using checkpoint (no re-parsing needed)
schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string", "description": "Invoice ID"},
        "total_amount": {"type": "number", "description": "Total due"}
    }
}

options = ExtractOptions(
    page_schema=json.dumps(schema),
    checkpoint_id=checkpoint_id
)
result = client.extract(options=options)
extracted = json.loads(result.extraction_schema_json)

The extract endpoint accepts the following parameters: file or file_url, page_schema or schema_id (one is required), schema_version, extraction_mode, mode, output_format, skip_cache, max_pages, page_range, save_checkpoint, checkpoint_id, webhook_url, and processing_location (e.g. "eu" — routes processing and storage to EU infrastructure; requires file_url or a pre-uploaded datalab:// reference instead of a multipart upload).

Using Saved Schemas

Instead of passing page_schema inline, you can save schemas to Datalab and reference them by ID. This avoids repeating the schema in every request and enables versioning.

curl -X POST https://www.datalab.to/api/v1/extract \
  -H "X-API-Key: $DATALAB_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "schema_id=sch_k8Hx9mP2nQ4v"

Pass schema_version to pin to a specific schema version; omit it to always use the latest. See Saved Schemas for full CRUD API reference.

Confidence Scoring

Extraction scoring is in beta.We’d love your feedback — reach out at support@datalab.to.Scoring is free.

Scoring runs asynchronously after cloud extraction in fast mode. After scoring succeeds, later polls of request_check_url include _score fields and a non-null extraction_score_average. Scoring can fail independently of extraction; use a bounded polling window and handle missing or null scores. Turbo, balanced, and accurate modes do not produce numeric confidence scores. No extra parameters or endpoints are needed. Each _score field is a {"score": int, "reasoning": str} object explaining what evidence was found or missing.

Score response format

Without scoring complete, extraction_schema_json contains fields and citations:

{
  "invoice_number": "INV-2024-001",
  "invoice_number_citations": ["block_123"],
  "total_amount": 1500.00,
  "total_amount_citations": ["block_456"]
}

Once scoring finishes, each field also gets a _score object, and the top-level response includes an extraction_score_average:

{
  "invoice_number": "INV-2024-001",
  "invoice_number_citations": ["block_123"],
  "invoice_number_score": {
    "score": 5,
    "reasoning": "Value found verbatim in the document header with a matching citation."
  },
  "total_amount": 1500.00,
  "total_amount_citations": ["block_456"],
  "total_amount_score": {
    "score": 4,
    "reasoning": "Amount found in the totals row; minor ambiguity due to a subtotal nearby."
  }
}

The top-level response also includes extraction_score_average (4.5 in this case), averaging all field scores. Score rubric:

Score	Meaning
5	High confidence — clear match with strong citation support
4	Good confidence — match found with minor ambiguity
3	Moderate confidence — partial match or uncertain citation
2	Low confidence — match is inferred or weakly supported
1	Very low confidence — no clear evidence found

See Confidence Scoring for a full walkthrough with code examples.

Auto-Generate Schemas

Don’t want to write schemas by hand? Use the schema generation endpoint to automatically suggest schemas for your document. This requires a checkpoint from a previous conversion:

import os, requests, json, time

headers = {"X-API-Key": os.getenv("DATALAB_API_KEY")}

# Step 1: Convert with checkpoint
with open("invoice.pdf", "rb") as f:
    resp = requests.post(
        "https://www.datalab.to/api/v1/convert",
        files={"file": ("invoice.pdf", f, "application/pdf")},
        data={"save_checkpoint": "true", "output_format": "markdown"},
        headers=headers
    )
check_url = resp.json()["request_check_url"]

# Poll until complete
while True:
    result = requests.get(check_url, headers=headers).json()
    if result.get("success") is False or result.get("status") == "failed":
        raise RuntimeError(result.get("error") or "Document processing failed")
    if result["status"] == "complete":
        if result.get("result_url"):
            download = requests.get(result["result_url"], timeout=60)
            download.raise_for_status()
            result = {**download.json(), **{k: v for k, v in result.items() if v is not None}}
        if result.get("success") is False:
            raise RuntimeError(result.get("error") or "Document processing failed")
        checkpoint_id = result["checkpoint_id"]
        break
    time.sleep(2)

# Step 2: Generate schemas
resp = requests.post(
    "https://www.datalab.to/api/v1/marker/extraction/gen_schemas",
    json={"checkpoint_id": checkpoint_id},
    headers=headers
)
gen_check_url = resp.json()["request_check_url"]

while True:
    result = requests.get(gen_check_url, headers=headers).json()
    if result.get("success") is False or result.get("status") == "failed":
        raise RuntimeError(result.get("error") or "Schema generation failed")
    if result["status"] == "complete":
        if result.get("result_url"):
            download = requests.get(result["result_url"], timeout=60)
            download.raise_for_status()
            result = {**download.json(), **{k: v for k, v in result.items() if v is not None}}
        if result.get("success") is False:
            raise RuntimeError(result.get("error") or "Document processing failed")
        suggestions = result["suggestions"]
        print("Simple schema:", suggestions["simple_schema"])
        print("Moderate schema:", suggestions["moderate_schema"])
        print("Complex schema:", suggestions["complex_schema"])
        break
    time.sleep(2)

The endpoint returns three schema options at different complexity levels — use the one that best matches your needs, then customize it.

Using Forge

Create and test schemas visually in Forge:

Upload a sample document
Define fields in the visual editor
Switch to JSON Editor to copy the schema
Test extraction before deploying

Next Steps

Balanced and Accurate Extraction Modes

Per-field verification, reasoning, and extraction status for compliance workflows

Saved Schemas

Create reusable schemas and reference them by ID — no need to repeat the schema in each request

Confidence Scoring

Score extraction results with per-field confidence ratings

Handling Long Documents

Strategies for extracting from 100+ page documents

General

Document Conversion

Document Segmentation

Form Filling

File Management

Pipelines

Create Document

Track Changes

Forge Evals

Structured Extraction

Quick Start

Extraction Modes

Schema Format

Tips for Better Extraction

Response

Citation Tracking

Schema Examples

Financial Document

Scientific Paper

Contract

Using Checkpoints

Using Saved Schemas

Confidence Scoring

Score response format

Auto-Generate Schemas

Using Forge

Next Steps

Balanced and Accurate Extraction Modes

Saved Schemas

Confidence Scoring

Handling Long Documents

​Quick Start

​Extraction Modes

​Schema Format

​Tips for Better Extraction

​Response

​Citation Tracking

​Schema Examples

​Financial Document

​Scientific Paper

​Contract

​Using Checkpoints

​Using Saved Schemas

​Confidence Scoring

​Score response format

​Auto-Generate Schemas

​Using Forge

​Next Steps

Balanced and Accurate Extraction Modes

Saved Schemas

Confidence Scoring

Handling Long Documents

Quick Start

Extraction Modes

Schema Format

Tips for Better Extraction

Response

Citation Tracking

Schema Examples

Financial Document

Scientific Paper

Contract

Using Checkpoints

Using Saved Schemas

Confidence Scoring

Score response format

Auto-Generate Schemas

Using Forge

Next Steps