Response Format

Classify returns the single best-matching category for a document, along with a confidence score and the reasoning behind the decision. This page explains every field in the response.

Response structure

A completed classify run looks like this (truncated for brevity). The classification result lives in output.

1 {
2   "object": "classify_run",
3   "id": "clr_Xj8mK2pL9nR4vT7qY5wZ",
4   "file": {
5     "object": "file",
6     "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
7     "name": "freight_invoice.pdf"
8   },
9   "status": "PROCESSED",
10   "output": {
11     "id": "invoice",
12     "type": "invoice",
13     "confidence": 0.97,
14     "insights": [
15       {
16         "type": "reasoning",
17         "content": "The document is titled \"Freight Invoice\" and lists line items, amounts, and payment terms."
18       }
19     ]
20   },
21   "reviewed": false,
22   "edited": false,
23   "usage": { "credits": 9 }
24 }

Top-level fields

Field	Type	Description
`object`	string	Always `"classify_run"`.
`id`	string	Unique identifier for the run (e.g. `clr_...`). Use it to fetch results later.
`file`	object	The processed file (`id`, `name`). Reusable as input to other endpoints.
`status`	string	`PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, or `CANCELLED`.
`output`	object \| null	The classification result. Present when `status` is `PROCESSED`. See The classification output.
`reviewed` / `edited`	boolean	Whether a human reviewed the run, and whether they changed the result. When `reviewed` is `true`, `initialOutput` and `reviewedOutput` are also populated.
`classifier` / `classifierVersion`	object \| null	The classifier and version used for the run. Present when a classifier reference was provided; not present when using inline `config`.
`config`	object	The full configuration used, including defaults that were applied.
`parseRunId`	string \| null	The ID of the parse run used for this classify run.
`dashboardUrl`	string	Link to view the run in the Extend dashboard.
`usage`	object	Credits consumed (`usage.credits`).
`failureReason` / `failureMessage`	string \| null	Machine-readable code and human-readable message. Present when `status` is `FAILED`.

The classification output

output holds a single matched classification. It is present when status is "PROCESSED".

1 {
2   "id": "invoice",
3   "type": "invoice",
4   "confidence": 0.95,
5   "insights": [
6     {
7       "type": "reasoning",
8       "content": "Document contains itemized charges and payment terms."
9     }
10   ]
11 }

Field	Type	Description
`id`	string	The unique identifier of the matched classification, as defined in your `classifications`.
`type`	string	The type of the matched classification.
`confidence`	number	A value between `0` and `1` indicating the model’s confidence in the classification, where `1` represents maximum confidence.
`insights`	array	Additional insights about the classification decision. See Insights.

Confidence

confidence is a number from 0 to 1 reflecting how sure the model is about the match. Use it to gate downstream processing — for example, route any classification below a threshold to manual review.

Insights

insights is an array explaining the classification decision. Each insight has a type and content.

1 {
2   "insights": [
3     {
4       "type": "reasoning",
5       "content": "This was classified as an invoice because it contains standard invoice elements including an invoice number, billing details, and itemized charges."
6     }
7   ]
8 }

Field	Type	Description
`type`	string	The type of insight. Always `"reasoning"` for now.
`content`	string	The content of the reasoning insight.