---
title: "Classify Response Format"
description: "Confidence scores, per-criterion reasoning, and all response fields"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Classify Response Format

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

```json
{
  "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](#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](/reference/pricing-migration#what-your-api-responses-look-like). |

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

**Python**

```python
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)
```

**Node.js**

```javascript
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**

```bash
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:

```json
{
  "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_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.

> **Tip:** 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.

**Python**

```python
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']}")
```

**cURL**

```bash
# 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)\""
```

---

## Related

- [Classify Overview](/classify/overview): Quick start, request parameters, and pipeline integration.

- [Best Practices](/classify/best-practices): Write better classification schemas for more accurate results.

Source: https://docs.reducto.ai/classify/response-format/index.mdx
