Guide: Batch Classification

The /v1/classify-batch endpoint classifies up to 1,000 text items in a single HTTP call. When used with a Classification Set, it automatically deduplicates near-identical items so you only pay for unique classifications.

Basic Usage

curl -X POST https://api.intentgine.dev/v1/classify-batch \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      "I love this product",
      "This is terrible",
      "I really love this product",
      "Just okay"
    ],
    "classification_set": "sentiment-v1"
  }'

Response

{
  "results": [
    { "input": "I love this product", "classification": "positive", "confidence": 0.96 },
    { "input": "This is terrible", "classification": "negative", "confidence": 0.94 },
    { "input": "I really love this product", "classification": "positive", "confidence": 0.96 },
    { "input": "Just okay", "classification": "neutral", "confidence": 0.88 }
  ],
  "metadata": {
    "requests_used": 3,
    "processed_count": 4,
    "requests_remaining": 9997
  }
}

Notice requests_used is 3, not 4 — “I love this product” and “I really love this product” were deduplicated as semantically equivalent.

How Deduplication Works

When you use a Classification Set (not inline classes), the batch endpoint:

1. Cache check — looks up each item in the semantic cache. Hits are returned immediately.
2. Embed & cluster — embeds all cache misses and groups items with ≥95% cosine similarity.
3. Classify unique representatives — sends only one item per cluster to the LLM.
4. Copy results — applies each representative’s classification to all items in its cluster.

Tip

Deduplication only activates when using a Classification Set. Inline classes skip this step and classify every item individually.

Billing

You’re charged per unique item in the batch. Cache hits are billed at half rate (1 request per 2 cached items, rounded up). Cache misses are billed at 1 request per unique item after deduplication.

Scenario	Items Sent	Cache Hits	Unique Misses	Charged
All unique, no cache	100	0	100	100 requests
All cached	100	100	0	50 requests
50% cached, rest unique	100	50	50	75 requests
50% cached, rest deduped	100	50	25	50 requests
All identical, no cache	100	0	1	1 request

Context

You can provide optional context to help the LLM make better decisions across all items:

{
  "data": ["It's running hot", "Fan is loud", "Screen flickers"],
  "classification_set": "support-category-v1",
  "context": "Customer support tickets for laptop hardware"
}

When to Use Batch

• Survey responses — classify hundreds of free-text answers at once
• Log analysis — categorise log entries or error messages in bulk
• Content moderation — screen user-generated content
• Data migration — tag or label existing records

Limits

Limit	Value
Max items per request	1,000
Max characters per item	4,096
Body size limit	2 MB

For items exceeding the character limit, see the Handling Large Payloads guide.