Skip to main content
Classify returns a category label, a per-criterion confidence breakdown for every category in your schema, and timing information. This page explains every field in the response.

​
Response Structure

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": {
    "category": "invoice"
  },
  "response_confidence": {
    "categories": [
      {
        "category": "invoice",
        "confidence": 1.0,
        "criteria_confidence": [
          {"criterion": "contains billing information", "confidence": "high"},
          {"criterion": "has itemized charges", "confidence": "high"},
          {"criterion": "includes payment details or amounts due", "confidence": "high"}
        ]
      },
      {
        "category": "contract",
        "confidence": 0.33,
        "criteria_confidence": [
          {"criterion": "contains legal terms and conditions", "confidence": "low"},
          {"criterion": "includes signature lines or parties involved", "confidence": "low"},
          {"criterion": "references obligations or agreements", "confidence": "high"}
        ]
      }
    ]
  },
  "usage": {
    "num_pages": 5,
    "num_categories": 2,
    "credits": 2.5
  },
  "duration": 1.23
}

​
Top-Level Fields

FieldTypeDescription
job_idstringUnique identifier for the classification job
result.categorystringThe best-matching category from your classification_schema. Always one of the category names you provided.
response_confidenceobjectPer-category and per-criterion confidence breakdown. null when no criteria are provided.
usageobjectPage count, category count, and credit consumption for this classification. See Usage Fields below. May be null.
durationnumberTime in seconds the classify request took. May be null.

​
Usage Fields

The usage object contains:
FieldTypeDescription
num_pagesintegerNumber of pages used as context for classification. Defaults to 5, or fewer if the document is shorter.
num_categoriesintegerNumber of categories in the classification_schema that were evaluated.
creditsnumberTotal credits consumed. Each page costs 0.5 credits. May be null.

​
Category Confidence Fields

Each entry in response_confidence.categories contains:
FieldTypeDescription
categorystringThe category name from your schema
confidencenumberFloat between 0 and 1 representing the fraction of criteria that matched for this category
criteria_confidencearrayPer-criterion evaluation results

​
Criteria Confidence Fields

Each entry in criteria_confidence contains:
FieldTypeDescription
criterionstringThe criterion text from your schema
confidencestring"high" (criterion matched the document) or "low" (criterion did not match)

​
Structured Confidence: Reasoning You Can Act On

Classify doesn’t just return a label. It returns a per-criterion confidence breakdown for every category you defined, not just the winner. This gives you structured, interpretable reasoning for why a document was classified the way it was. Each criterion you define becomes a yes/no evaluation. The confidence score for a category is the fraction of its criteria that matched (high). In the example above, "invoice" scored 1.0 because all 3 criteria matched, while "contract" scored 0.33 because only 1 of 3 criteria matched. This structured output is useful in several ways:
  • Auditability. You can trace exactly which criteria drove a classification decision. If an invoice was misclassified, inspect the criteria_confidence to see which criteria matched or didn’t.
  • Threshold-based routing. Instead of blindly trusting result.category, check the confidence score. If the top category scores below a threshold (e.g., 0.6), flag it for human review rather than routing it automatically.
  • Ambiguity detection. If two categories score similarly (e.g., 0.67 and 0.55), the document may be ambiguous. Use this signal to trigger a different workflow or request additional information.
  • Schema refinement. Low-confidence classifications across your pipeline tell you which criteria need to be more specific. The per-criterion breakdown pinpoints exactly which criteria are too broad or overlapping.
Think of criteria as a structured checklist. This makes the classification decision transparent and programmatically accessible, not just a black-box label.

​
Example: Confidence-Based Routing

Use the per-category confidence scores to build routing logic that handles uncertain classifications gracefully. 
import requests

API_KEY = "YOUR_REDUCTO_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Classify the document
classify_resp = requests.post(
    "https://platform.reducto.ai/classify",
    headers=HEADERS,
    json={
        "input": "YOUR_FILE_ID",
        "classification_schema": [
            {"category": "invoice", "criteria": ["contains billing information", "has itemized charges"]},
            {"category": "contract", "criteria": ["contains legal terms", "includes signature lines"]},
        ],
    },
)
result = classify_resp.json()

# Extract the winning category and its confidence
category = result["result"]["category"]
confidence = next(
    c for c in result["response_confidence"]["categories"]
    if c["category"] == category
)

if confidence["confidence"] >= 0.7:
    # High confidence: route automatically
    print(f"Routing {category} automatically (confidence: {confidence['confidence']})")
else:
    # Low confidence: flag for human review
    print(f"Flagging for review: {category} (confidence: {confidence['confidence']})")
    print("Criteria breakdown:")
    for c in confidence["criteria_confidence"]:
        print(f"  {c['criterion']}: {c['confidence']}")

Classify Overview

Quick start, request parameters, and pipeline integration.

Best Practices

Write better classification schemas for more accurate results.