API Reference

Extract

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Extract Jobs

extract.list(ExtractListParams**kwargs) -> SyncPaginatedCursor[ExtractV2Job]

GET/api/v2/extract

List extraction jobs with optional filtering and pagination.

Filter by configuration_id, status, file_input, or creation date range. Results are returned newest-first. Use expand=configuration to include the full configuration used, and expand=extract_metadata for per-field metadata.

ParametersExpand Collapse

configuration_id: Optional[str]

Filter by configuration ID

created_at_on_or_after: Optional[Union[str, datetime, null]]

Include items created at or after this timestamp (inclusive)

formatdate-time

created_at_on_or_before: Optional[Union[str, datetime, null]]

Include items created at or before this timestamp (inclusive)

formatdate-time

document_input_type: Optional[str]

Filter by document input type (file_id or parse_job_id)

Deprecateddocument_input_value: Optional[str]

Deprecated: use file_input instead

expand: Optional[SequenceNotStr[str]]

Additional fields to include: configuration, extract_metadata

file_input: Optional[str]

Filter by file input value

job_ids: Optional[SequenceNotStr[str]]

Filter by specific job IDs

organization_id: Optional[str]

page_size: Optional[int]

Number of items per page

page_token: Optional[str]

Token for pagination

project_id: Optional[str]

status: Optional[Literal["PENDING", "THROTTLED", "RUNNING", 3 more]]

Filter by status

One of the following:

"PENDING"

"THROTTLED"

"RUNNING"

"COMPLETED"

"FAILED"

"CANCELLED"

ReturnsExpand Collapse

class ExtractV2Job: …

An extraction job.

id: str

Unique job identifier (job_id)

created_at: datetime

Creation timestamp

formatdate-time

file_input: str

File ID or parse job ID that was extracted

project_id: str

Project this job belongs to

status: str

Current job status.

• PENDING — queued, not yet started
• RUNNING — actively processing
• COMPLETED — finished successfully
• FAILED — terminated with an error
• CANCELLED — cancelled by user

updated_at: datetime

Last update timestamp

formatdate-time

configuration: Optional[ExtractConfiguration]

Extract configuration combining parse and extract settings.

data_schema: Dict[str, Union[Dict[str, object], List[object], str, 3 more]]

JSON Schema defining the fields to extract. Validate with the /schema/validate endpoint first.

One of the following:

Dict[str, object]

List[object]

str

float

bool

cite_sources: Optional[bool]

Include citations in results

confidence_scores: Optional[bool]

Include confidence scores in results

extract_version: Optional[str]

Extract algorithm version. Use ‘latest’ for the default pipeline, a date string (e.g. ‘2026-01-08’), or ‘continuous’ to opt into schema-guided splitting for documents with repeating entities.

extraction_target: Optional[Literal["per_doc", "per_page", "per_table_row"]]

Granularity of extraction: per_doc returns one object per document, per_page returns one object per page, per_table_row returns one object per table row

One of the following:

"per_doc"

"per_page"

"per_table_row"

max_pages: Optional[int]

Maximum number of pages to process. Omit for no limit.

minimum1

parse_config_id: Optional[str]

Saved parse configuration ID to control how the document is parsed before extraction

parse_tier: Optional[str]

Parse tier to use before extraction. Defaults to the extract tier if not specified.

system_prompt: Optional[str]

Custom system prompt to guide extraction behavior

target_pages: Optional[str]

Comma-separated page numbers or ranges to process (1-based). Omit to process all pages.

tier: Optional[Literal["cost_effective", "agentic"]]

Extract tier: cost_effective (5 credits/page) or agentic (15 credits/page)

One of the following:

"cost_effective"

"agentic"

configuration_id: Optional[str]

Saved extract configuration ID used for this job, if any

error_message: Optional[str]

Error details when status is FAILED

extract_metadata: Optional[ExtractJobMetadata]

Extraction metadata.

field_metadata: Optional[ExtractedFieldMetadata]

Metadata for extracted fields including document, page, and row level info.

document_metadata: Optional[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]

Per-field metadata keyed by field name from your schema. Scalar fields (e.g. vendor) map to a FieldMetadataEntry with citation and confidence. Array fields (e.g. items) map to a list where each element contains per-sub-field FieldMetadataEntry objects, indexed by array position. Nested objects contain sub-field entries recursively.

One of the following:

Dict[str, object]

List[object]

str

float

bool

page_metadata: Optional[List[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]]

Per-page metadata when extraction_target is per_page

One of the following:

Dict[str, object]

List[object]

str

float

bool

row_metadata: Optional[List[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]]

Per-row metadata when extraction_target is per_table_row

One of the following:

Dict[str, object]

List[object]

str

float

bool

parse_job_id: Optional[str]

Reference to the ParseJob ID used for parsing

parse_tier: Optional[str]

Parse tier used for parsing the document

extract_result: Optional[Union[Dict[str, Union[Dict[str, object], List[object], str, 3 more]], List[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]], null]]

Extracted data conforming to the data_schema. Returns a single object for per_doc, or an array for per_page / per_table_row.

One of the following:

Dict[str, Union[Dict[str, object], List[object], str, 3 more]]

One of the following:

Dict[str, object]

List[object]

str

float

bool

List[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]

One of the following:

Dict[str, object]

List[object]

str

float

bool

metadata: Optional[Metadata]

Job-level metadata.

usage: Optional[ExtractJobUsage]

Extraction usage metrics.

num_document_tokens: Optional[int]

Number of document tokens

num_output_tokens: Optional[int]

Number of output tokens

num_pages_extracted: Optional[int]

Number of pages extracted

List Extract Jobs

Python

HTTP

TypeScript

Python

import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
page = client.extract.list()
page = page.items[0]
print(page.id)

200 example

{
  "items": [
    {
      "id": "ext-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "created_at": "2019-12-27T18:11:19.117Z",
      "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "project_id": "prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "COMPLETED",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "configuration": {
        "data_schema": {
          "foo": {
            "foo": "bar"
          }
        },
        "cite_sources": true,
        "confidence_scores": true,
        "extract_version": "latest",
        "extraction_target": "per_doc",
        "max_pages": 10,
        "parse_config_id": "cfg-11111111-2222-3333-4444-555555555555",
        "parse_tier": "fast",
        "system_prompt": "Extract all monetary values in USD. If a currency is not specified, assume USD.",
        "target_pages": "1,3,5-7",
        "tier": "cost_effective"
      },
      "configuration_id": "cfg-11111111-2222-3333-4444-555555555555",
      "error_message": "error_message",
      "extract_metadata": {
        "field_metadata": {
          "document_metadata": {
            "items": [
              {
                "amount": {
                  "citation": [
                    {
                      "matching_text": "$10.00",
                      "page": 1
                    }
                  ],
                  "confidence": 1
                },
                "description": {
                  "citation": [
                    {
                      "matching_text": "$10/month",
                      "page": 1
                    }
                  ],
                  "confidence": 0.998
                }
              }
            ],
            "total": {
              "citation": "bar",
              "confidence": "bar"
            },
            "vendor": {
              "citation": "bar",
              "confidence": "bar",
              "extraction_confidence": "bar",
              "parsing_confidence": "bar"
            }
          },
          "page_metadata": [
            {
              "foo": {
                "foo": "bar"
              }
            }
          ],
          "row_metadata": [
            {
              "foo": {
                "foo": "bar"
              }
            }
          ]
        },
        "parse_job_id": "parse_job_id",
        "parse_tier": "parse_tier"
      },
      "extract_result": {
        "foo": {
          "foo": "bar"
        }
      },
      "metadata": {
        "usage": {
          "num_document_tokens": 0,
          "num_output_tokens": 0,
          "num_pages_extracted": 0
        }
      }
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}

Returns Examples

200 example

{
  "items": [
    {
      "id": "ext-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "created_at": "2019-12-27T18:11:19.117Z",
      "file_input": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "project_id": "prj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "COMPLETED",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "configuration": {
        "data_schema": {
          "foo": {
            "foo": "bar"
          }
        },
        "cite_sources": true,
        "confidence_scores": true,
        "extract_version": "latest",
        "extraction_target": "per_doc",
        "max_pages": 10,
        "parse_config_id": "cfg-11111111-2222-3333-4444-555555555555",
        "parse_tier": "fast",
        "system_prompt": "Extract all monetary values in USD. If a currency is not specified, assume USD.",
        "target_pages": "1,3,5-7",
        "tier": "cost_effective"
      },
      "configuration_id": "cfg-11111111-2222-3333-4444-555555555555",
      "error_message": "error_message",
      "extract_metadata": {
        "field_metadata": {
          "document_metadata": {
            "items": [
              {
                "amount": {
                  "citation": [
                    {
                      "matching_text": "$10.00",
                      "page": 1
                    }
                  ],
                  "confidence": 1
                },
                "description": {
                  "citation": [
                    {
                      "matching_text": "$10/month",
                      "page": 1
                    }
                  ],
                  "confidence": 0.998
                }
              }
            ],
            "total": {
              "citation": "bar",
              "confidence": "bar"
            },
            "vendor": {
              "citation": "bar",
              "confidence": "bar",
              "extraction_confidence": "bar",
              "parsing_confidence": "bar"
            }
          },
          "page_metadata": [
            {
              "foo": {
                "foo": "bar"
              }
            }
          ],
          "row_metadata": [
            {
              "foo": {
                "foo": "bar"
              }
            }
          ]
        },
        "parse_job_id": "parse_job_id",
        "parse_tier": "parse_tier"
      },
      "extract_result": {
        "foo": {
          "foo": "bar"
        }
      },
      "metadata": {
        "usage": {
          "num_document_tokens": 0,
          "num_output_tokens": 0,
          "num_pages_extracted": 0
        }
      }
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}