Skip to main content
Balanced and accurate modes run an extraction pipeline with independent verification. Scalar fields include metadata describing the supporting evidence and extraction reasoning. When available, verification metadata records the independent check; nested objects and arrays retain their structure. Before you begin, make sure you have:
  1. A Datalab account with an API key (new accounts include $5 in free credits)
  2. Python 3.10+ installed
  3. The Datalab SDK: pip install datalab-python-sdk
  4. 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.

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:
The _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.verification can describe list completeness.
  • Arrays of scalar values can have aggregate _citations, per-item metadata in _meta.items, and list-level _meta.verification.
Check both item-level results and list completeness. A list-level 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, or FAIL_*
  • 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