> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.datalab.to/llms.txt
> Use this file to discover all available pages before exploring further.
# Structured Extraction
> Extract structured data from documents using JSON schemas with the Datalab SDK.
A completed request can return `success=False` and `error` without raising an SDK exception. Check `result.success` before reading the output.
Python SDK 0.5.0 does not download signed regional results automatically. For EU requests, use the [REST polling and download flow](/docs/recipes/conversion/conversion-api-overview#regional-result-downloads).
## Basic Usage
```python theme={null}
import json
from datalab_sdk import DatalabClient, ExtractOptions
client = DatalabClient()
# Define a JSON schema for extraction
page_schema = json.dumps({
"type": "object",
"properties": {
"invoice_number": {"type": "string", "description": "Invoice number"},
"total": {"type": "number", "description": "Total amount due"},
"vendor": {"type": "string", "description": "Vendor or company name"},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {"type": "string"},
"amount": {"type": "number"}
}
}
}
},
})
options = ExtractOptions(page_schema=page_schema)
result = client.extract("invoice.pdf", options=options)
if not result.success:
raise RuntimeError(result.error or "Document processing failed")
# Access the extracted data
extracted = json.loads(result.extraction_schema_json)
print(extracted)
```
## Extract Options
Use `ExtractOptions` to configure extraction behavior:
| Option | Type | Default | Description |
| - | - | - | - |
| `page_schema` | str | Required unless using `schema_id` | JSON schema with `type="object"` and a root `properties` object. Mutually exclusive with `schema_id`. |
| `schema_id` | str | None | ID of a saved extraction schema (e.g. `sch_k8Hx9mP2nQ4v`). Mutually exclusive with `page_schema`. |
| `schema_version` | int | None | Schema version to pin to. Only valid with `schema_id`. |
| `checkpoint_id` | str | None | Checkpoint ID from a previous `convert()` call |
| `mode` | str | `"fast"` | Parse mode: `"fast"`, `"balanced"`, `"accurate"`. Controls document parsing quality. |
| `extraction_mode` | str | None | `"turbo"`, `"fast"`, `"balanced"`, or `"accurate"`. When omitted, the team default applies. Turbo returns JSON without parsed output or citations and cannot reuse checkpoints. |
| `output_format` | str | `"markdown"` | Output format: `"markdown"`, `"html"`, `"json"`, `"chunks"` |
| `save_checkpoint` | bool | `False` | Save checkpoint for reuse with subsequent calls |
| `max_pages` | int | None | Maximum number of pages to process |
| `page_range` | str | None | Specific pages to process (e.g., `"0-5,10"`). For spreadsheets, filters by sheet index. |
| `skip_cache` | bool | `False` | Skip cached results, force reprocessing |
| `webhook_url` | str | None | Webhook URL for completion notification |
Set `extraction_mode` independently from the parse `mode`. For balanced or accurate extraction, set `mode="accurate"` explicitly to match the REST default; the SDK otherwise sends `mode="fast"`. See [Balanced and Accurate Extraction Modes](/docs/recipes/structured-extraction/balanced-mode).
## Checkpoint Reuse
Use checkpoints to avoid re-parsing a document when running extraction after conversion. First convert with `save_checkpoint=True`, then extract using the returned `checkpoint_id`:
```python theme={null}
import json
from datalab_sdk import DatalabClient, ConvertOptions, ExtractOptions
client = DatalabClient()
# Step 1: Convert and save a checkpoint
convert_options = ConvertOptions(
mode="accurate",
save_checkpoint=True,
)
convert_result = client.convert("report.pdf", options=convert_options)
print(convert_result.markdown)
# Step 2: Extract using the checkpoint (no re-parsing needed)
page_schema = json.dumps({
"type": "object",
"properties": {
"title": {"type": "string", "description": "Document title"},
"author": {"type": "string", "description": "Author name"},
"date": {"type": "string", "description": "Publication date"},
"summary": {"type": "string", "description": "Brief summary of the document"},
},
})
extract_options = ExtractOptions(
page_schema=page_schema,
checkpoint_id=convert_result.checkpoint_id,
)
extract_result = client.extract(options=extract_options)
extracted = json.loads(extract_result.extraction_schema_json)
print(extracted)
```
## Extraction Result
The result object contains the extracted data alongside standard conversion fields:
```python theme={null}
result = client.extract("invoice.pdf", options=options)
# Extracted structured data (JSON string)
extracted = json.loads(result.extraction_schema_json)
print(extracted["invoice_number"])
print(extracted["total"])
# Standard conversion fields are also available
print(result.success)
print(result.markdown)
print(result.page_count)
print(result.cost_breakdown)
```
## Async Usage
```python theme={null}
import asyncio
import json
from datalab_sdk import AsyncDatalabClient, ExtractOptions
async def extract_data():
async with AsyncDatalabClient() as client:
page_schema = json.dumps({
"type": "object",
"properties": {
"title": {"type": "string", "description": "Document title"},
"author": {"type": "string", "description": "Author name"},
},
})
options = ExtractOptions(page_schema=page_schema)
result = await client.extract("document.pdf", options=options)
return json.loads(result.extraction_schema_json)
extracted = asyncio.run(extract_data())
print(extracted)
```
## Next Steps
Learn more about structured extraction patterns and best practices.
Segment documents into logical sections using schemas.
Convert documents to Markdown, HTML, JSON, or chunks.
Process multiple documents efficiently in parallel.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.