- 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_KEYenvironment 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.Choosing an Extraction Mode
Accurate uses the same verification format as balanced. It can take longer and cost more; evaluate both on your documents. Turbo mode skips parsing and returns extracted JSON without citations or verification.
The rates above cover extraction. Parsing is billed separately when it runs, and complex requests can incur usage-based charges. See Billing and pricing.
Schema Size
Balanced and accurate extraction accept up to 750 schema fields. Count scalar fields inside objects and arrays; repeated array items do not multiply the schema field count. Schemas above this limit fail with an error asking you to split or simplify them. Large schemas on short documents are partitioned during extraction. The 750-field limit applies across document lengths. Free accounts without a payment method also have a processing-cost limit; a request that exceeds it returns an error asking you to reduce the workload or upgrade.Quick Start
extraction_mode controls the extraction pipeline (turbo, fast, balanced, or accurate). This is separate from mode, which controls the document parsing stage (fast, balanced, or accurate). You can combine them independently — for example, mode="fast" with extraction_mode="balanced".Set ExtractOptions(extraction_mode="balanced") or extraction_mode="accurate" in the SDK. Its parse mode defaults to "fast", so set mode="accurate" explicitly to match the REST default for these extraction modes. When extraction mode is omitted, the team’s configured default applies.Response Format
For a scalar property in an object, balanced and accurate modes return three sibling keys. The_citations sibling is the same format as fast mode for compatibility — balanced mode adds _meta with richer metadata on top:
_citations key is shared with fast mode — if you switch between modes, citation-consuming code continues to work. The _meta key is available in balanced and accurate modes and contains the full audit trail.
Field Metadata
Scalar-field_meta objects contain:
Nested Objects and Arrays
- Nested objects keep metadata beside their scalar properties; the parent object does not automatically have its own
_meta. - Arrays of objects keep each item’s field metadata inside that item. A separate array
_meta.verificationcan describe list completeness. - Arrays of scalar values can have aggregate
_citations, per-item metadata in_meta.items, and list-level_meta.verification.
PASS alone does not establish that every field in every item passed.
Extraction Status
Verification Status
A status other than
PASS, or missing verification metadata, needs review before using the value in a workflow that requires verification.
Building Workflows with Verification Metadata
The example below checks the flat scalar schema from Quick Start. For nested objects and arrays, also traverse their field metadata and check list completeness before approving the document.Common Workflow Patterns
- Apply your approval policy only after checking every requested field and any list-level verification; a model verification result is not a guarantee of correctness
- Flag for review when any requested field or verification result is missing, or a status is
NOT_RESOLVABLE,PENDING,ITEMS_MISSING, orFAIL_* - Show citations to reviewers so they can verify in seconds — each field links back to specific blocks in the document
- Use reasoning as an audit trail — for compliance workflows, the per-field reasoning documents exactly how each value was produced, with block-level citations back to the source document
Next Steps
Structured Extraction Overview
Schema format, response structure, and extraction tips
Confidence Scoring
Numeric per-field confidence scores for fast extraction only
Saved Schemas
Save and version schemas for reuse across requests
Handling Long Documents
Tips for extracting from 100+ page documents