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
| Field | Type | Description |
|---|---|---|
job_id |
string | Unique identifier for the classification job |
result.category |
string | The best-matching category from your classification_schema. Always one of the category names you provided. |
extra_metadata |
object | {"grouping": "<group>"} when the request set category_groups. The value is "ungrouped" if the winning category is in no group. Omitted when the request did not set category_groups. |
response_confidence |
object | Per-category and per-criterion confidence breakdown. null when no criteria are provided. |
usage |
object | Page count, category count, and credit consumption for this classification. See Usage Fields below. May be null. |
duration |
number | Time in seconds the classify request took. May be null. |
Usage Fields
The usage object contains:
| Field | Type | Description |
|---|---|---|
num_pages |
integer | Number of pages used as context for classification. Defaults to 5, or fewer if the document is shorter. |
num_categories |
integer | Number of categories in the classification_schema that were evaluated. |
credits |
number | Total credits consumed. Each page costs 0.5 credits. May be null. |
usage_breakdown |
object | Raw usage quantities. Present only for accounts on per-product pricing, where the credit fields are null. See Pricing Migration Guide. |
Category Confidence Fields
Each entry in response_confidence.categories contains:
| Field | Type | Description |
|---|---|---|
category |
string | The category name from your schema |
confidence |
number | Float between 0 and 1 representing the fraction of criteria that matched for this category |
criteria_confidence |
array | Per-criterion evaluation results |
Criteria Confidence Fields
Each entry in criteria_confidence contains:
| Field | Type | Description |
|---|---|---|
criterion |
string | The criterion text from your schema |
confidence |
string | "high" (criterion matched the document) or "low" (criterion did not match) |
Grouping Metadata
Use category_groups to map detailed categories to broader groups for downstream routing.
from reducto import Reducto
client = Reducto()
response = client.classify.run(
input="https://example.com/invoice.pdf",
classification_schema=[
{
"category": "invoice",
"criteria": ["itemized charges", "amount due", "vendor details"],
},
{
"category": "receipt",
"criteria": ["completed transaction", "items purchased", "total paid"],
},
{
"category": "contract",
"criteria": ["legal terms", "parties and obligations", "signature lines"],
},
],
category_groups={
"financial": ["invoice", "receipt"],
"legal": ["contract"],
},
)
print(response)import Reducto from 'reductoai';
const client = new Reducto();
const response = await client.classify.run({
input: 'https://example.com/invoice.pdf',
classification_schema: [
{
category: 'invoice',
criteria: ['itemized charges', 'amount due', 'vendor details'],
},
{
category: 'receipt',
criteria: ['completed transaction', 'items purchased', 'total paid'],
},
{
category: 'contract',
criteria: ['legal terms', 'parties and obligations', 'signature lines'],
},
],
category_groups: {
financial: ['invoice', 'receipt'],
legal: ['contract'],
},
});
console.log(response);curl -X POST https://platform.reducto.ai/classify \
-H "Authorization: Bearer $REDUCTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "https://example.com/invoice.pdf",
"classification_schema": [
{
"category": "invoice",
"criteria": ["itemized charges", "amount due", "vendor details"]
},
{
"category": "receipt",
"criteria": ["completed transaction", "items purchased", "total paid"]
},
{
"category": "contract",
"criteria": ["legal terms", "parties and obligations", "signature lines"]
}
],
"category_groups": {
"financial": ["invoice", "receipt"],
"legal": ["contract"]
}
}'The response includes the matched group:
{
"result": {
"category": "invoice"
},
"extra_metadata": {
"grouping": "financial"
}
}Route on extra_metadata.grouping when your downstream pipeline is shared by several detailed categories.
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_confidenceto 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.67and0.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.
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 and inspect confidence
RESPONSE=$(curl -s -X POST https://platform.reducto.ai/classify \
-H "Authorization: Bearer $REDUCTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "YOUR_FILE_ID",
"classification_schema": [
{"category": "invoice", "criteria": ["contains billing information", "has itemized charges"]},
{"category": "contract", "criteria": ["contains legal terms", "includes signature lines"]}
]
}')
# Get the category and confidence
CATEGORY=$(echo $RESPONSE | jq -r '.result.category')
CONFIDENCE=$(echo $RESPONSE | jq -r ".response_confidence.categories[] | select(.category == \"$CATEGORY\") | .confidence")
echo "Category: $CATEGORY (confidence: $CONFIDENCE)"
# Show per-criterion breakdown
echo "Criteria breakdown:"
echo $RESPONSE | jq -r ".response_confidence.categories[] | select(.category == \"$CATEGORY\") | .criteria_confidence[] | \" \(.criterion): \(.confidence)\""