Classify 任务会返回同一个对象 —— classify 任务 —— 来自 POST /api/v2/classify、GET /api/v2/classify/{job_id} 以及取消端点。SDK 的 client.classify.create()、client.classify.get()、client.classify.wait_for_completion() 与 client.classify.run() 返回的也是它。本页列出该对象的每个字段及其含义。要写规则、跑任务请看快速上手；请求侧见 Classify API 参考。

任务外层结构

字段	类型	说明
id	string	任务标识。传给 GET /api/v2/classify/{job_id} 使用。
status	string	任务状态。见任务状态。
file_input	string	该任务所运行的文件 ID 或 parse 任务 ID。
document_input_type	string	file_input 指向什么：file_id、parse_job_id 或 url。
parse_job_id	string 或 null	与本次分类关联的 Parse 任务（若有）。
configuration	object	任务实际使用的配置：rules、mode 与 parsing_configuration。无论任务是内联创建还是来自已保存配置，该字段始终存在。
configuration_id	string 或 null	本任务使用的已保存配置 ID（若有）。
result	object 或 null	分类结果。仅当 status 为 COMPLETED 时存在。见 result。
error_message	string 或 null	任务失败原因，当 status 为 FAILED 时给出。
transaction_id	string 或 null	创建时提供的幂等键（若有）。重复使用同一个键会返回原任务。
project_id	string	任务所属的 project。
user_id	string	创建该任务的用户。
created_at, updated_at	datetime	创建时间与最后更新时间戳。
usage	object 或 null	该任务消耗的额度。仅在 GET /api/v2/classify/{job_id} 带 expand=usage 时返回。见单个任务计费的额度。

任务状态

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

轮询直到状态落到三个终态之一，或者用 client.classify.wait_for_completion(job.id)。client.classify.run() 一次调用完成创建与等待，并在任务失败时抛出异常 —— 能走到下一行就说明它成功了。

result

每个任务只分类一份文档，并返回一个含三个字段的 result 对象：

字段	类型	说明
type	string 或 null	命中规则的那个 type 标签。没有规则命中时为 null。
confidence	number	该命中正确的置信度，取值 0.0 到 1.0。
reasoning	string	文档为何命中（或未命中）所返回的那条规则。

type 始终取自 configuration.rules 里的某个 type 标签（或为 null），所以你可以直接对它做分支判断。标签只包含字母数字、空格、连字符与下划线；见核心概念。

以合同分类示例为例（它使用 affiliate_agreements 与 co_branding 两条规则），一个已完成任务的 type 与 reasoning 如下：

Classification Result: affiliate_agreements
Classification Reason: The document is titled 'MARKETING AFFILIATE AGREEMENT' and repeatedly refers to one party as the 'Marketing Affiliate.' The agreement outlines the rights and obligations of the 'Marketing Affiliate' (MA) to market, sell, and support certain technology products [...] Therefore, the best match is 'affiliate_agreements' with very high confidence.

读取 result 之前务必先检查 status（或 result is None）：失败或被取消的任务没有 result，原因记在 error_message 里。

单个任务计费的额度

取任务时加上 expand=usage 就能看到它计费的额度：

终端窗口

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v2/classify/{JOB_ID}?project_id={PROJECT_ID}&expand=usage' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

{
  "id": "clj-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "COMPLETED",
  "usage": {
    "credits": 3.0,
    "parse_credits": 3.0
  }
}

• 当 file_input 是一个文件时，Classify 会在其上运行一个 Parse 任务并通过该任务计费。parse_credits 就是那个 Parse 任务的额度，credits 是合计。
• 当 file_input 是你自己创建的某个 Parse 任务时，parse_credits 为 null 且 credits 为 0。这些额度归属于那个 Parse 任务，请用 GET /api/v2/parse/{job_id}?expand=usage 查看。
• 任务 COMPLETED 之前 usage 为 null。此后有一小段时间 credits 与 parse_credits 仍是 null（要等计费系统记账），所以请继续轮询，别把 null 读成零。

套餐额度与组织级用量见计费与用量。

已保存的配置

用 configuration_id 创建的任务，会以该已保存配置中存储的规则、mode 与解析配置来运行。响应里两者都记录：

• configuration_id 回显所用的已保存配置 ID。用内联 configuration 创建的任务该字段为 null。
• configuration 是任务实际运行所用的、已解析开的配置，因此即使已保存配置后来被改过，也仍能把 result.type 与 configuration.rules[].type 对上。
• 一个请求可以同时带 configuration_id 与内联 configuration。你显式设置的内联字段会覆盖已保存值，没写的字段则沿用已保存配置；响应里的 configuration 展示合并后的结果。

更新已保存配置会影响之后引用它的新任务；已完成的任务保留它当时运行所用的配置。见用已保存的配置分类。

多个文件的结果怎么取

一个任务只分类一份文档，因此一批文件就会产生一一对应的多个任务。收集结果的做法：

• 每个文件提交一个任务，使用同一份内联 configuration 或同一个 configuration_id，再逐个读取每个任务的 result。
• GET /api/v2/classify 返回一页任务，含 items、用于取下一页的 next_page_token（没有更多页时不出现），以及可选的 total_size。可用 configuration_id、status 或 job_ids 过滤。SDK 里 client.classify.list(configuration_id=...) 返回一个可直接迭代的游标，它会自动替你取后续页。
• 如果提交可能需要重试，创建时传一个 transaction_id：复用同一个键会返回原任务而不会新建第二个。

获取完整响应

下载示例所用到的那份发票：

终端窗口

curl -fL -o document.pdf https://media.githubusercontent.com/media/run-llama/llama-datasets/main/llama_agents/invoice-contracts/invoice-2-1.pdf

import os
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])

file_obj = client.files.create(file="document.pdf", purpose="classify")

job = client.classify.create(
    file_input=file_obj.id,
    configuration={
        "rules": [
            {
                "type": "invoice",
                "description": "Documents that contain an invoice number, invoice date, bill-to section, and line items with totals.",
            },
            {
                "type": "receipt",
                "description": "Short purchase receipts, typically from POS systems, with merchant, items and total, often a single page.",
            },
        ],
    },
)
job = client.classify.wait_for_completion(job.id)

print(job.status)
print(job.document_input_type, job.file_input)
if job.result is None:
    print(f"No result: {job.error_message}")
else:
    print(job.result.type)        # "invoice", "receipt", or None
    print(job.result.confidence)  # 0.0 to 1.0
    print(job.result.reasoning)