抽取任务返回 extract_result，其数据与你的 schema 对应。要引用与置信度得分请请求 extract_metadata，要计费 credit 请请求 usage。完整的任务对象见 Extract API 参考。

任务外层结构

字段	类型	说明
id	string	任务标识，带 ext- 前缀。传给 GET /api/v2/extract/{job_id}。
status	string	任务状态。见任务状态。
file_input	string	该任务所运行的文件 ID（dfl-...）或 parse 任务 ID（pjb-...）。
project_id	string	任务所属的 project。
created_at, updated_at	datetime	创建时间与最后更新时间戳。
error_message	string 或 null	当 status 为 FAILED 时给出错误详情。
extract_result	object、array 或 null	抽出的数据，形状由你的 data_schema 决定。见extract_result。
extract_metadata	object 或 null	引用、置信度得分与 parse 细节。需要 expand=extract_metadata。见extract_metadata。
configuration	object 或 null	任务实际使用的配置。取回时需要 expand=configuration。见已保存的配置。
configuration_id	string 或 null	本任务使用的已保存配置 ID（若有）。
usage	object 或 null	取回时显示该任务计费的 credit。需要 expand=usage。见用量与 credit。

展开响应

GET /api/v2/extract/{job_id} 默认返回 extract_result，并省略较重的那几个字段。要带上它们，请加上一个或多个 expand 取值。创建与取消两类响应不接受 expand，且总是包含 configuration。

expand 取值	增加了什么
extract_metadata	逐字段的引用与置信度得分
configuration	任务实际所用的、已解析的配置
usage	该任务计费的 credit

列出端点 GET /api/v2/extract 接受 expand=configuration 与 expand=extract_metadata，返回 items、指向下一页的 next_page_token，以及可选的 total_size。

任务状态

status	含义
PENDING	已排队，尚未开始。
RUNNING	正在处理。
COMPLETED	已结束；extract_result 已填充。
FAILED	因错误终止；请读 error_message。
CANCELLED	被用户取消。

轮询直到状态落到三个终态之一，或交给 client.extract.wait_for_completion(job.id) 替你完成。

extract_result

extract_result 包含由你的 data_schema 定义的字段与取值类型。Extract 把 schema 应用到文档上并返回一个对象。你 schema 里的数组在该对象内仍是数组。

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

缺失取值的情况见必填与可选字段。

extract_metadata

extract_metadata 需要 expand=extract_metadata。请在配置里开启 cite_sources 或 confidence_scores，相应字段才会包含在内。

字段	说明
field_metadata	逐字段的引用与置信度得分。
parse_job_id	本次抽取所用的 Parse 任务 ID（可用时）。
parse_tier	那个 Parse 任务的档位（可用时）。

field_metadata

逐字段元数据从 field_metadata.document_metadata 读取。元数据遵循你的 schema，含嵌套对象与数组。例如 items[0].amount 的元数据位于 document_metadata.items[0].amount。

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

引用

设 cite_sources: true 会为每个字段返回一个 citation 数组。每条引用指明一个来源位置：

键	说明
page	页号，从 1 开始。
matching_text	得出该取值所依据的源文本。
bounding_boxes	页上的位置，形如 {x, y, w, h}。
page_dimensions	页面尺寸，形如 {width, height}。

Turbo 的引用只含 page 与 matching_text。电子表格模式不返回引用也不返回置信度得分。见引用。

置信度得分

设 confidence_scores: true 会为每个字段返回一个 0 到 1 的 confidence 得分。可用它决定哪些取值需要复核。如何选阈值见置信度得分。

已保存的配置

configuration_id 指明本任务所用的已保存配置。内联配置时它为 null。请求 expand=configuration 可取回解析后的参数，含 schema、档位、扩展设置以及具体的版本号。见使用已保存的配置。

用量与 credit

usage 随 expand=usage 返回，描述该任务消耗了什么：

键	说明
credits	该任务计费的 credit 总额：下面两项之和，只计入已经记录下来的部分。
extract_credits	抽取本身计费的 credit。
parse_credits	Extract 为本任务所创建那个 Parse 任务的计费。当 file_input 是你自己创建的 Parse 任务时它为 null，因为那些 credit 属于那个 Parse 任务。

任务完成前 usage 为 null；在计费系统记录之前，credit 数值也可能一直是 null，对这类待定的值请再次轮询。当多个 Extract 任务共用同一个 Parse 任务时，汇总用量时 parse_credits 只应计一次。见查看某任务计费了多少 credit。

获取完整响应

下面先带着引用与置信度得分跑一个任务，再用它的任务 ID 一次请求三种展开。这里用的是引用示例 里的 NVIDIA 10-K：

终端窗口

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)