Classify response format

A Classify job returns one object, the classify job, from POST /api/v2/classify, GET /api/v2/classify/{job_id}, and the cancel endpoint. The SDKs return the same object from client.classify.create(), client.classify.get(), client.classify.wait_for_completion(), and client.classify.run(). This page lists every field in that object and what each one means. For writing rules and running jobs, see Getting started; for the request side, see the Classify API reference.

Job envelope

Field	Type	Description
id	string	Job identifier. Pass it to GET /api/v2/classify/{job_id}.
status	string	Job state. See Job status.
file_input	string	The file ID or parse job ID the job ran on.
document_input_type	string	What file_input refers to: file_id, parse_job_id, or url.
parse_job_id	string or null	The Parse job associated with this classification, if any.
configuration	object	The configuration the job ran with: rules, mode, and parsing_configuration. Always present, whether the job was created inline or from a saved configuration.
configuration_id	string or null	Saved configuration ID used for the job, if any.
result	object or null	The classification. Present only when status is COMPLETED. See result.
error_message	string or null	Why the job failed, when status is FAILED.
transaction_id	string or null	The idempotency key supplied at creation, if any. Reusing a key returns the original job.
project_id	string	Project the job belongs to.
user_id	string	User who created the job.
created_at, updated_at	datetime	Creation and last-update timestamps.

Job status

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

Poll until the status is one of the three terminal values, or use client.classify.wait_for_completion(job.id). client.classify.run() creates the job and waits in one call, and raises if the job fails, so reaching the next line means it succeeded.

result

Each job classifies a single document and returns a single result with three fields:

Field	Type	Description
type	string or null	The type label of the rule that matched. Null when no rule matched.
confidence	number	Confidence that the match is correct, from 0.0 to 1.0.
reasoning	string	Why the document matched, or did not match, the returned rule.

type is always one of the type labels in configuration.rules (or null), so you can switch on it directly. Labels contain only alphanumeric characters, spaces, hyphens, and underscores; see Concepts.

From the contract classification example, which uses the rules affiliate_agreements and co_branding, the type and reasoning of a completed job read:

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.

Always check status (or result is None) before reading result: a failed or cancelled job has no result, and error_message carries the reason.

Saved configurations

A job created with configuration_id runs with the rules, mode, and parsing configuration stored in that saved configuration. The response records both:

• configuration_id echoes the saved configuration ID. It is null for jobs created with an inline configuration.
• configuration is the resolved configuration the job ran with, so result.type can be matched against configuration.rules[].type even after the saved configuration has been edited.
• A request may carry both configuration_id and an inline configuration. The inline fields you set override the saved values, and the fields you leave out fall through to the saved configuration; configuration in the response shows the merged result.

Updating a saved configuration changes future jobs that reference it; completed jobs keep the configuration they ran with. See Classify with a saved configuration.

Results across many files

One job classifies one document, so a batch of files produces one job per file. To collect the results:

• Submit one job per file, with the same inline configuration or the same configuration_id, and read each job’s result.
• GET /api/v2/classify returns a page of jobs as items, a next_page_token to fetch the next page (absent when there are no more pages), and an optional total_size. Filter by configuration_id, status, or job_ids to narrow the list. In the SDKs, client.classify.list(configuration_id=...) returns a cursor you can iterate directly; it fetches the following pages for you.
• Pass a transaction_id on creation when you may retry a submission: reusing the key returns the original job instead of creating a second one.

Fetch the full response

import os
from llama_cloud import LlamaCloud

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

file_obj = client.files.create(file="path/to/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)