--- title: Classify response format | Developer Documentation description: Field-by-field reference for the Classify job response — the job envelope and statuses, the result object with the matched rule type, confidence score and reasoning, saved configurations, and how to collect results across many files. --- 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](/llamaparse/classify/sdk/index.md); for the request side, see the [Classify API reference](https://developers.llamaindex.ai/reference/resources/classify/). ## 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](#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](#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](/llamaparse/classify/#concepts/index.md). From the [contract classification example](/llamaparse/classify/examples/classify_contract_types/index.md), 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](/llamaparse/classify/examples/classify_with_saved_config/index.md). ## 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) ```