Skip to content
Guide
Extract
Guides

Extract response format

Reference for Extract v2 job responses, extracted data, citations, confidence scores, and usage credits.

Extract jobs return extract_result with data matching your schema. Request extract_metadata for citations and confidence scores, and usage for billed credits. See the Extract API reference for the complete job object.

Field Type Description
id string Job identifier, prefixed ext-. Pass it to GET /api/v2/extract/{job_id}.
status string Job state. See Job status.
file_input string The file ID (dfl-...) or parse job ID (pjb-...) the job ran on.
project_id string Project the job belongs to.
created_at, updated_at datetime Creation and last-update timestamps.
error_message string or null Error details when status is FAILED.
extract_result object, array, or null The extracted data, shaped by your data_schema. See extract_result.
extract_metadata object or null Citations, confidence scores, and parse details. Requires expand=extract_metadata. See extract_metadata.
configuration object or null The configuration the job ran with. On retrieval, requires expand=configuration. See Saved configurations.
configuration_id string or null Saved configuration ID used for the job, if any.
usage object or null Credits billed against the job on retrieval. Requires expand=usage. See Usage and credits.

GET /api/v2/extract/{job_id} returns extract_result by default and omits the heavier fields. Add one or more expand values to include them. The create and cancel responses take no expand and always include configuration.

expand value Adds
extract_metadata Per-field citations and confidence scores
configuration The resolved configuration the job ran with
usage Credits billed against the job

The list endpoint, GET /api/v2/extract, accepts expand=configuration and expand=extract_metadata and returns items, a next_page_token for the next page, and an optional total_size.

status Meaning
PENDING Queued, not yet started.
RUNNING Actively processing.
COMPLETED Finished; extract_result is populated.
FAILED Terminated with an error; read error_message.
CANCELLED Cancelled by the user.

Poll until the status is one of the three terminal values, or let client.extract.wait_for_completion(job.id) do it for you.

extract_result contains the fields and value types defined by your data_schema. Extract applies the schema to the document and returns one object. Arrays in your schema remain arrays inside that object.

{
"company_name": "NVIDIA Corporation",
"fiscal_year": 2025,
"revenue": 130497
}

For missing values, see Required and optional fields.

extract_metadata requires expand=extract_metadata. Enable cite_sources or confidence_scores in the configuration to include those fields.

Field Description
field_metadata Per-field citations and confidence scores.
parse_job_id ID of the Parse job used for extraction, when available.
parse_tier Tier of that Parse job, when available.

Read field metadata from field_metadata.document_metadata. The metadata follows your schema, including nested objects and arrays. For example, metadata for items[0].amount is at document_metadata.items[0].amount.

{
"field_metadata": {
"document_metadata": {
"company_name": {
"citation": [{"page": 1, "matching_text": "NVIDIA CORPORATION"}],
"confidence": 0.99
}
}
}
}

Set cite_sources: true to return a citation array for each field. Each citation identifies a source location:

Key Description
page 1-based page number.
matching_text Source text for the extracted value.
bounding_boxes Locations on the page as {x, y, w, h}.
page_dimensions Page size as {width, height}.

Turbo citations include page and matching_text only. Spreadsheet mode does not return citations or confidence scores. See Citations.

Set confidence_scores: true to return a confidence score from 0 to 1 for each field. Use the score to choose which values need review. See Confidence scores for choosing a threshold.

configuration_id identifies the saved configuration used for the job. It is null for inline configurations. Request expand=configuration to retrieve the resolved parameters, including the schema, tier, extensions, and concrete version. See Using saved configurations.

usage, returned with expand=usage, describes what the job consumed:

Key Description
credits Total credits billed against the job: the sum of the two components below, counting only those already recorded.
extract_credits Credits billed for the extraction itself.
parse_credits Credits billed against the Parse job that Extract created for this job. null when file_input was a Parse job you created yourself, because those credits belong to that Parse job.

usage is null until completion. Credit values can remain null until billing records them. Poll again for pending values. When several Extract jobs use the same Parse job, count parse_credits once when totaling usage. See Check the credits a job billed.

Run a job with citations and confidence scores on, then request all three expansions with its job ID. This uses the NVIDIA 10-K from the citations example:

Terminal window
curl -fL -o nvda_10k.pdf https://raw.githubusercontent.com/run-llama/llama_cloud_services/refs/heads/main/examples/extract/data/sec_filings/nvda_10k.pdf
import os
from llama_cloud import LlamaCloud
client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])
file = client.files.create(file="./nvda_10k.pdf", purpose="extract")
completed = client.extract.run(
file_input=file.id,
configuration={
"data_schema": {
"type": "object",
"properties": {
"company_name": {"type": "string"},
"fiscal_year": {"type": "integer"},
"revenue": {"type": "integer", "description": "Total revenue, in millions"},
},
},
"tier": "agentic",
"target_pages": "1,38", # the cover page and the revenue summary, of 130
"cite_sources": True,
"confidence_scores": True,
},
)
job = client.extract.get(completed.id, expand=["extract_metadata", "configuration", "usage"])
print(job.extract_result)
print(job.extract_metadata.field_metadata.document_metadata)
print(job.usage)
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/