Extract response format

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.

Job envelope

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.

Expanding the response

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.

Job status

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

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

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.

field_metadata

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
      }
    }
  }
}

Citations

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.

Confidence scores

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.

Saved configurations

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 and credits

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.

Fetch the full response

For a completed job, request all three expansions with its job ID:

import os
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])
job = client.extract.get("JOB_ID", expand=["extract_metadata", "configuration", "usage"])

print(job.extract_result)
print(job.extract_metadata.field_metadata.document_metadata)
print(job.usage)