Skip to content
Developer Documentation
Guide
Extract
Guides
Configuring Extract

Configuring Extract

Everything needed to configure an Extract job in one place — core concepts, schema design and restrictions, configuration options, and performance tips.

This page is the map for an Extract job: the concepts a job is built from, how to write the schema that drives it, every option you can set alongside that schema, and the practices that keep extraction accurate as you scale.

For the field-by-field request reference, see the Extract API Reference. For the extra metadata a job can return, see Metadata Extensions.

Core concepts

Section titled “Core concepts”

LlamaExtract is designed to be a flexible and scalable extraction platform. At the core of the platform are the following concepts:

  • Extraction Configurations: Reusable settings including schema, tier, and extraction options.
  • Data Schema: Structured definition for the data you want to extract in JSON/Pydantic format. See detailed explanation below.
  • Extraction Jobs: Asynchronous tasks that extract structured data from documents using a configuration.
  • Extraction Runs: The results of an extraction job including the extracted data and other metadata.

Data schema

Section titled “Data schema”

The Data Schema defines the structure of the data you want to extract from your documents. It is a JSON Schema that specifies the fields, types, and descriptions for the information you need.

While the schema is fundamentally a JSON Schema (supporting a subset of the full JSON Schema specification), our Python SDK allows you to use Pydantic models for a more Pythonic experience with type validation and IDE support.

Fields, types, size limits, and the JSON Schema subset that Extract accepts are covered in Schema design and restrictions below.

Schema design and restrictions

Section titled “Schema design and restrictions”

The schema is the most important part of an extraction configuration. It defines the structure of the data you want back, and its field descriptions are what steer the extraction model.

How to define your schema

Section titled “How to define your schema”

A schema is made of fields. Each field has a name, a type, and optionally a description.

  • Field names — Use clear, stable names that match how you’ll use the data (e.g. invoice_number, vendor_name). These become the keys in the extracted JSON.
  • Field descriptions — Descriptions are additional context for the underlying LLM. They are not only for documentation: the extraction model uses them to decide what to extract. Use descriptions to guide the model on what the value for the field could be—for example, what the field means, where it usually appears in the document, acceptable formats, or examples. Better descriptions typically lead to more accurate and consistent extraction.

Required and optional fields

Section titled “Required and optional fields”

In JSON Schema, an object’s required array lists the properties that must be present. Listed properties are required, and unlisted properties are optional. Use "required": [] to make every property optional. Nullability is separate. Include a null branch when a field may return null.

This schema makes invoice_number required and start_date optional and nullable:

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "start_date": {
      "anyOf": [{ "type": "string" }, { "type": "null" }]
    }
  },
  "required": ["invoice_number"]
}

You can also write the nullable field as "start_date": { "type": ["string", "null"] }. Extract accepts both forms. Nullable arrays and objects keep their items and properties.

We recommend specifying required explicitly for correctness. If required is omitted, Extract treats every property as required for convenience, so you do not have to list every field. This default differs from standard JSON Schema, where an omitted required array makes all properties optional.

Schema restrictions

Section titled “Schema restrictions”

LlamaExtract only supports a subset of the JSON Schema specification. While limited, it should be sufficient for a wide variety of use-cases.

  • An omitted required array makes every property required in Extract. See Required and optional fields when data may be absent.
  • In Pydantic, use Optional[T] or T | None to make a field nullable. Set a default of None if the field should also be optional.
  • Root node must be of type object.
  • Schema nesting must be limited to within 7 levels.
  • The important fields are key names/titles, type and description. Fields for formatting, default values, etc. are not supported. If you need these, you can add the restrictions to your field description and/or use a post-processing step. e.g. default values can be supported by making a field optional and then setting "null" values from the extraction result to the default value.
  • Additional schema restrictions:
    • Maximum properties: 5,000 total properties across the entire schema.
    • Maximum total string content: 120,000 characters for all strings (field names, descriptions, enum values, etc.) combined.
    • Maximum raw JSON schema size: 150,000 characters for the raw JSON schema string.
  • If you hit these limits for complex extraction use cases, consider restructuring your extraction workflow to fit within these constraints, e.g. by extracting subsets of fields and later merging them together.

Schema size

Section titled “Schema size”

Cost-effective, Agentic, and Agentic Plus support schemas up to 3,200 fields. Cost-effective and Agentic require version 2.1 or later for large schemas.

Size is the number of leaf fields in the schema you submit, meaning the scalar values at the bottom of the tree. It does not depend on the document or on how much data comes back.

  • Objects don’t count themselves, only the leaves inside them. {"address": {"city": ..., "zip": ...}} is 2 fields.
  • Arrays count their item schema once, no matter how many items get extracted. An array of 40 line items with 5 fields each counts as 5 fields, not 200.
  • An array of scalars, e.g. {"tags": ["string"]}, counts as 1 field.
  • $ref is expanded at each place it’s used. If three fields all point at the same 10-field Address definition, that’s 30 fields, not 10. Reusing a definition keeps your schema readable but doesn’t make it smaller.

A schema with 30 top-level scalars and a table of 10 columns is 40 fields.

Tips & best practices

Section titled “Tips & best practices”
  • Try to limit schema nesting to 3-4 levels.
  • Make fields optional when data might not always be present (specially boolean and int fields where defaults for missing values could cause confusion).
  • When you want to extract a variable number of entities, use an array type. However, note that you cannot use an array type for the root node.
  • Use descriptive field names and detailed descriptions. Use descriptions to pass formatting instructions or few-shot examples.
  • Above all, start simple and iteratively build your schema to incorporate requirements.

Automatic schema generation

Section titled “Automatic schema generation”

Instead of manually defining schemas, you can use LlamaExtract’s automatic schema generation feature. The system can generate a schema based on:

  • A natural language prompt: Describe what data you want to extract
  • A sample file: Upload a document and let the system infer the schema from its structure
  • An existing schema to refine: Provide a base schema and let the system improve or extend it

You can combine these inputs — for example, provide both a sample file and a prompt to guide the generation.

Using the REST API

Section titled “Using the REST API”
Terminal window
curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/schema/generate?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Extract invoice details including invoice number, date, vendor name, line items with descriptions and amounts, and total amount",
    "file_id": "optional-file-id-for-sample-document"
  }'

For the full API documentation, see the LlamaExtract API Reference.

Defining schemas with SDKs

Section titled “Defining schemas with SDKs”

The Python SDK can be installed using

Terminal window
pip install llama-cloud>=2.1

Schemas can be defined using either Pydantic models or JSON Schema:

Section titled “Using Pydantic (recommended)”
from pydantic import BaseModel, Field
from typing import List, Optional


class Experience(BaseModel):
    company: str = Field(description="Company name")
    title: str = Field(description="Job title")
    start_date: Optional[str] = Field(description="Start date of employment")
    end_date: Optional[str] = Field(description="End date of employment")


class Resume(BaseModel):
    name: str = Field(description="Candidate name")
    experience: List[Experience] = Field(description="Work history")


schema = Resume.model_json_schema()

Using JSON Schema

Section titled “Using JSON Schema”
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "Candidate name"},
        "experience": {
            "type": "array",
            "description": "Work history",
            "items": {
                "type": "object",
                "properties": {
                    "company": {
                        "type": "string",
                        "description": "Company name",
                    },
                    "title": {"type": "string", "description": "Job title"},
                    "start_date": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "Start date of employment",
                    },
                    "end_date": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "End date of employment",
                    },
                },
            },
        },
    },
}

With your schema, you can directly run extractions using the SDK:

from llama_cloud import LlamaCloud


client = LlamaCloud(api_key="your_api_key")


file_obj = client.files.create(file="path/to/your/document.pdf", purpose="extract")


job = client.extract.create(
    file_input=file_obj.id,
    configuration={
            "data_schema": schema,
            "tier": "agentic",
        },
)


# Poll for completion
while job.status not in ("COMPLETED", "FAILED", "CANCELLED"):
    import time; time.sleep(2)
    job = client.extract.get(job.id)

Configuration options

Section titled “Configuration options”

The schema decides what comes back. The options below decide how the job runs — which tier interprets the document, which pages it reads, and what extra metadata it returns.

Tiers

Section titled “Tiers”

Extract tiers determine how much effort LlamaExtract puts into producing structured data from a document.

Agentic Plus provides the highest extraction quality across document types, including short or straightforward documents. Use it when you want the best result and can accept higher cost and latency. It may take longer on long or complex documents as it puts more iterative effort into the result.

Agentic balances quality, cost, and latency across a broad range of documents, including mixed layouts and tables.

Cost Effective prioritizes lower cost and latency for straightforward extraction, especially at high volume. It works best when fields and layouts are predictable and ambiguity is limited.

Cost-effective, Agentic, and Agentic Plus support schemas up to 3,200 fields.

Turbo is the speed tier. It prepares the document itself rather than running a separate Parse step, which is what makes it fast and also means it produces no parse output: there is no parsed text or Markdown to retrieve from a Turbo job, only the structured result your schema asks for.

Latency is the reason to choose Turbo. On the short documents it targets, it typically returns in seconds where the other tiers take tens of seconds. On our extraction benchmark it scores above Cost Effective on accuracy; choose an Agentic tier when maximum accuracy is what matters. Turbo bills one all-in per-page rate with no separate parse charge, and that rate is higher than Agentic: it is a premium option that pays for speed, not a cheaper one — see pricing.

Reach for Turbo when latency is user-facing, such as interactive apps and upload-and-review flows, or when you run high volumes of short, predictable documents.

Turbo carries real constraints:

CapabilityTurbo
Input formatsPDF, JPG, PNG only
ParseNo parse step and no parse output; parse_tier and parse_config_id are ignored if sent
CitationsSupported, text-level only; granular bounding boxes are rejected
Confidence scoresSupported

Each extract tier has a default parse tier chosen to balance cost and quality. You can override the parse tier in Advanced Settings when your workload needs lower parsing cost or higher-quality document interpretation. Turbo is the exception: it runs without a parse step, so there is no parse tier to override. See pricing for the default combinations and additive costs.

Versions

Section titled “Versions”

Set configuration.version to a version name such as 2.5, or latest for the newest compatible release for the selected tier. Dates (YYYY-MM-DD) are also supported, which will use the latest version on or before the specified date.

Spreadsheet mode

Section titled “Spreadsheet mode”

Spreadsheet mode (spreadsheet_mode) extracts directly from an Excel or CSV workbook (.xlsx, .xls, .csv), working with its cells rather than flattening the file into text. It runs on the cost_effective, agentic, and agentic_plus tiers and does not produce citations or confidence scores. Cost-effective and Agentic require version 2.1 or later. Spreadsheet mode bills by workbook size at the selected tier’s extract rate, with no separate Parse charge. See Extraction pricing.

Reach for it when a workbook holds structured, predictably shaped data you want mapped onto a schema — positions in a fund workbook, line items in an exported ledger. Turn it on with spreadsheet_mode and, optionally, sheet_names to limit extraction to specific worksheets (names match exactly; omit for every sheet; on spreadsheets sheet_names replaces target_pages):

from pydantic import BaseModel, Field


class Position(BaseModel):
    ticker: str = Field(description="Ticker or symbol")
    market_value: float = Field(description="Position market value")


class Portfolio(BaseModel):
    positions: list[Position] = Field(description="One entry per holding in the workbook")


job = client.extract.create(
    file_input=file_obj.id,   # an uploaded .xlsx / .xls / .csv
    configuration={
        "data_schema": Portfolio.model_json_schema(),
        "tier": "agentic",
        "spreadsheet_mode": True,
        "sheet_names": ["Holdings"],  # optional; omit for every sheet
    },
)

When you don’t know a workbook’s shape ahead of time, extract every cell into a generic “tidy cell” schema — each cell carrying its row- and column-header path — instead of a targeted one:

class Cell(BaseModel):
    row_hierarchy: list[str | None]     # row-label path to this cell
    column_hierarchy: list[str | None]  # column-header path above it
    value: str | None


class Table(BaseModel):
    title: str
    cells: list[Cell]


class Workbook(BaseModel):
    tables: list[Table]

Advanced settings

Section titled “Advanced settings”

Under Advanced Settings in the UI you can fine-tune how extraction runs:

  • Parse tier: Select the parsing tier used to interpret the input document before extraction. This uses the same v2 parse tiers as LlamaParse (for example, cost_effective, agentic, and agentic_plus). See Tiers for details. Not applicable on Turbo, which runs without a parse step.
  • Cite sources: Enable cite sources to attach citations to extracted fields so you can trace every value back to its origin in the document. On Turbo, citations are text-level and carry no bounding boxes.
  • Confidence scores: Enable confidence scores to get per-field confidence signals alongside extracted output.
  • System prompt: Provide a system prompt to globally guide the extractor (for example, “Prefer the most recent fiscal year if multiple are present”, or “Return numbers as plain numerals without currency symbols”).

System prompt

Section titled “System prompt”
  • System Prompt: Any additional system level instructions for the extraction. Note that you should use the schema descriptions to pass field-level instructions, few-shot examples, formatting instructions, etc.

Page range and context window

Section titled “Page range and context window”

  • Page Range: Specify which pages to extract from by providing comma-separated page numbers or ranges (1-based indexing). For example, use 1,3,5-7,9 to extract pages 1, 3, pages 5 through 7, and page 9. You can also use ranges like 1-3,8-10 to extract the first three pages and pages 8 through 10. Page numbers are 1-based, meaning the first page is page 1. This option is useful when you only need to extract data from specific sections of large documents.

  • Context Window: Number of pages to pass as context for long document extraction. This is useful when extracting from large documents where you need context from surrounding pages. This is configurable via the extraction tier and system prompt. Larger values keep more of the surrounding document intact, which helps when you need to see multi-page tables or invoices in one pass. Smaller values advance through the file more aggressively and are better when you need exhaustive coverage of dense lists.

Metadata extensions

Section titled “Metadata extensions”

For additional extraction features that provide enhanced metadata and insights, see the Metadata Extensions page which covers:

  • Citations: Source tracing for extracted fields
  • Confidence Scores: Quantitative confidence measures

These extensions return additional metadata in the extract_metadata field but may impact processing time.

Setting configuration options

Section titled “Setting configuration options”

You can configure these options when creating an extraction job using either the REST API or Python SDK.

SDKs

Section titled “SDKs”

First, install the Python SDK:

Terminal window
pip install llama-cloud>=2.1

Here’s how to set various configuration options:

import time
from llama_cloud import LlamaCloud, AsyncLlamaCloud


client = LlamaCloud(api_key="your_api_key")


schema = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string", "description": "Name of the company"},
        "revenue": {"type": "number", "description": "Annual revenue in USD"}
    }
}


file_obj = client.files.create(file="path/to/your/document.pdf", purpose="extract")
file_id = file_obj.id


job = client.extract.create(
    file_input=file_id,
    configuration={
        "data_schema": schema,
        "extraction_target": "per_doc",          # Document extraction
        "tier": "agentic",                       # cost_effective, agentic, agentic_plus
        "version": "2.5",                        # Extract version name
        "system_prompt": "Focus on the most recent financial data",
        "target_pages": "1-5,10-15",             # Extract from specific pages
        "cite_sources": True,                    # Enable citations
        "confidence_scores": True,               # Enable confidence scores
    },
)


# Poll for completion
while job.status not in ("COMPLETED", "FAILED", "CANCELLED"):
    time.sleep(2)
    job = client.extract.get(job.id)

REST API

Section titled “REST API”

You can configure these options using the REST API when creating an extraction job:

Terminal window
curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v2/extract?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_input": "{FILE_ID}",
    "configuration": {
      "data_schema": {
        "type": "object",
        "properties": {
          "company_name": {"type": "string", "description": "Name of the company"},
          "revenue": {"type": "number", "description": "Annual revenue in USD"}
        }
      },
      "extraction_target": "per_doc",
      "tier": "agentic",
      "version": "2.5",
      "system_prompt": "Focus on the most recent financial data",
      "target_pages": "1-5,10-15",
      "cite_sources": true,
      "confidence_scores": true
    }
  }'

Configuration reference

Section titled “Configuration reference”
OptionTypeDefaultDescription
Tier
tierstring”agentic”Extraction tier: cost_effective, agentic (default), agentic_plus. turbo is also accepted — see Tiers for its constraints.
versionstring”latest”Extract version name, such as “2.5”, or “latest” for the newest compatible release for the selected tier. Dates (YYYY-MM-DD) are also supported, which will use the latest version on or before the specified date.
System Prompt
system_promptstringnullAdditional system-level instructions
Page Range and Context
target_pagesstringnullComma-separated page numbers or ranges to process (1-based, e.g., “1,3,5-7”). Pages are processed in the order listed, so “3,1,2” feeds page 3 first, then 1, then 2.
max_pagesintegernullMaximum number of pages to process
Metadata Extensions
cite_sourcesbooleanfalseEnable source citations
confidence_scoresbooleanfalseEnable confidence scores
Spreadsheet
spreadsheet_modebooleanfalseExtract directly from an Excel/CSV workbook by reading its cells. Supported on cost_effective, agentic, and agentic_plus; Cost-effective and Agentic require version 2.1 or later. No citations or confidence scores. See pricing.
sheet_namesarraynullWorksheet names to extract when spreadsheet_mode is on (case-sensitive, exact match). Overrides target_pages; omit to extract every sheet.

Performance tips

Section titled “Performance tips”

Overall best practices

Section titled “Overall best practices”

For maximum extraction success:

  1. Start with the agentic tier for debugging: When troubleshooting extraction issues, use the agentic tier which uses the most capable models. If extraction succeeds with agentic, you can try cost_effective to see if quality holds for your use case. If extraction fails even with agentic, the issue is likely in your schema design (e.g., ambiguous field descriptions). If wall-clock latency is your constraint rather than quality, see the Turbo tier: it extracts pages in parallel with no parse step and returns in seconds on PDF and image inputs.

    import time
    from llama_cloud import LlamaCloud
    

    client = LlamaCloud(api_key="your_api_key")
    

    schema = {
        "type": "object",
        "properties": {
            "company_name": {"type": "string", "description": "Name of the company"},
            "revenue": {"type": "number", "description": "Annual revenue in USD"},
        },
    }
    

    file_obj = client.files.create(file="path/to/your/document.pdf", purpose="extract")
    

    # Start debugging with agentic tier
    job = client.extract.create(
        file_input=file_obj.id,
        configuration={
            "data_schema": schema,
            "extraction_target": "per_doc",
            "tier": "agentic",
        },
    )
    

    # Poll for completion
    while job.status not in ("COMPLETED", "FAILED", "CANCELLED"):
        time.sleep(2)
        job = client.extract.get(job.id)
    

    print(job.extract_result)

  2. Start small and iterate: Begin with a subset of your data or schema to validate your extraction approach and iterate on your schema description (e.g. adding examples, formatting instructions etc.) to get better accuracy before scaling.

  3. Design clear, focused schemas: Prefer precise short descriptions over verbose fields that try to do too much. See Schema design and restrictions and Avoid complex field transformations.

  4. Leverage document structure: Use page ranges, sections, and chunking strategies to optimize processing. See Configuration options.

  5. Combine tools strategically: Extract excels at extracting information from documents. Focus on leveraging this strength while using complementary tools for computational tasks and validation (e.g., heavy calculations are better handled in a post-processing step).

Extracting from tables and ordered lists

Section titled “Extracting from tables and ordered lists”

The situation: When working with documents containing tables, spreadsheets (CSV/Excel), or ordered lists of entities, you want every row or item extracted, not just the first few.

Model the rows as an array field: Describe one row as an object and put it in an array field of your schema. Extract returns every row in that array, and document-level fields such as titles, dates, and totals can sit next to it in the same schema, so a single job covers both.

{
  "type": "object",
  "properties": {
    "report_title": {"type": "string", "description": "Title of the report"},
    "line_items": {
      "type": "array",
      "description": "Every row of the line item table, in document order",
      "items": {
        "type": "object",
        "properties": {
          "line_item": {"type": "string", "description": "Name of the line item"},
          "amount": {"type": "number", "description": "Amount in USD"}
        }
      }
    }
  }
}

If the table sits in a known part of a long document, set target_pages to that range.

Avoid complex field transformations

Section titled “Avoid complex field transformations”

Don’t embed business logic in field descriptions. Extract clean data first, then compute in your application code.

# ❌ Problematic: Too much logic in the field description
problematic_field = {
    "calculated_score": {
        "type": "number",
        "description": "If revenue > 1M, multiply by 0.8, else if revenue < 500K multiply by 1.2, otherwise use the base score from table 3, but only if the date is after 2020 and the category is not 'exempt'"
    }
}


# ✅ Better: Simple extraction, handle logic separately
better_schema = {
    "revenue": {"type": "number", "description": "Total revenue in dollars"},
    "base_score": {"type": "number", "description": "Base score value from the scoring table"},
    "date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
    "category": {"type": "string", "description": "Business category"}
}


# Then handle calculations in your application code:
def calculate_final_score(extracted_data):
    revenue = extracted_data["revenue"]
    if revenue > 1000000:
        return extracted_data["base_score"] * 0.8
    elif revenue < 500000:
        return extracted_data["base_score"] * 1.2
    return extracted_data["base_score"]
Note for AI agents: this documentation is built for programmatic access. - Overview of all docs: https://developers.llamaindex.ai/llms.txt - Any page is available as raw Markdown by appending index.md to its URL — e.g. https://developers.llamaindex.ai/llamaparse/parse/getting_started/index.md - Agent-friendly REST search APIs live under https://developers.llamaindex.ai/api/ — search (BM25 full-text), grep (regex), read (fetch a page), and list (browse the doc tree). See https://developers.llamaindex.ai/llms.txt for parameters. - A hosted documentation MCP server is available at https://developers.llamaindex.ai/mcp. If you support MCP, you can ask the user to install it for browsing these docs directly (an alternative to the REST API). Setup: https://developers.llamaindex.ai/for-agents/mcp/ - Other LlamaIndex tooling for agents — the LlamaParse Platform MCP server, agent skills and plugins, and the n8n node — is mapped at https://developers.llamaindex.ai/for-agents/