Skip to navigation
CapabilitiesClassification

Classification 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.

{
  "object": "classify_run",
  "id": "clr_Xj8mK2pL9nR4vT7qY5wZ",
  "file": {
    "object": "file",
    "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
    "name": "freight_invoice.pdf"
  },
  "status": "PROCESSED",
  "output": {
    "id": "invoice",
    "type": "invoice",
    "confidence": 0.97,
    "insights": [
      {
        "type": "reasoning",
        "content": "The document is titled \"Freight Invoice\" and lists line items, amounts, and payment terms."
      }
    ]
  },
  "reviewed": false,
  "edited": false,
  "usage": { "credits": 9 }
}

Top-level fields

FieldTypeDescription
objectstringAlways "classify_run".
idstringUnique identifier for the run (e.g. clr_...). Use it to fetch results later.
fileobjectThe processed file (id, name). Reusable as input to other endpoints.
statusstringPENDING, PROCESSING, PROCESSED, FAILED, or CANCELLED.
outputobject | nullThe classification result. Present when status is PROCESSED. See The classification output.
reviewed / editedbooleanWhether a human reviewed the run, and whether they changed the result. When reviewed is true, initialOutput and reviewedOutput are also populated.
classifier / classifierVersionobject | nullThe classifier and version used for the run. Present when a classifier reference was provided; not present when using inline config.
configobjectThe full configuration used, including defaults that were applied.
parseRunIdstring | nullThe ID of the parse run used for this classify run.
dashboardUrlstringLink to view the run in the Extend dashboard.
usageobjectCredits consumed (usage.credits).
failureReason / failureMessagestring | nullMachine-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".

{
  "id": "invoice",
  "type": "invoice",
  "confidence": 0.95,
  "insights": [
    {
      "type": "reasoning",
      "content": "Document contains itemized charges and payment terms."
    }
  ]
}
FieldTypeDescription
idstringThe unique identifier of the matched classification, as defined in your classifications.
typestringThe type of the matched classification.
confidencenumberA value between 0 and 1 indicating the model’s confidence in the classification, where 1 represents maximum confidence.
insightsarrayAdditional 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.

{
  "insights": [
    {
      "type": "reasoning",
      "content": "This was classified as an invoice because it contains standard invoice elements including an invoice number, billing details, and itemized charges."
    }
  ]
}
FieldTypeDescription
typestringThe type of insight. Always "reasoning" for now.
contentstringThe content of the reasoning insight.