Batch classification
Send up to 1,000 products, track one parent batch and retrieve every EU or China classification.
One request creates a durable parent batch of 1 to 1,000 rows. The service schedules durable sub-batches of 100 and runs at most 32 classifications concurrently.
| Submitted rows | Internal sub-batches | Identifier tracked by the client |
|---|---|---|
| 500 | 5 | 1 batch_id |
| 1,000 | 10 | 1 batch_id |
The client does not split the file. It retains the batch_id and a stable id for each row.
The full schema is available in the OpenAPI contract.
Routes
| Jurisdiction | Create | Track | Key scope |
|---|---|---|---|
| European Union | POST /v1/classify/batch | GET /v1/classify/batch/{batch_id} | classify |
| China | POST /v1/classify-china/batch | GET /v1/classify-china/batch/{batch_id} | classify_china |
Create a batch
Each row must contain a description, images, or both.
| Field | Required | Description |
|---|---|---|
items | Yes | 1 to 1,000 rows |
items[].id | Recommended | Stable ERP reference. Generated when omitted |
items[].content | Conditional | Description and objective characteristics |
items[].image_urls | Conditional | Up to 5 HTTPS images |
items[].taric_code | China only | Optional comparative reference, never an automatic conversion |
analysis_mode | No | operational by default or legal_deep |
locale | No | fr, en, es or de |
curl -sS -X POST "https://api.thetradehub.eu/v1/classify/batch" \
-H "X-API-Key: $TTH_API_KEY" \
-H "Idempotency-Key: erp-import-2026-09" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"id": "SKU-001", "content": "Bluetooth headset with active noise cancellation"},
{"id": "SKU-002", "content": "Stainless steel centrifugal pump for food liquids"}
],
"analysis_mode": "operational",
"locale": "en"
}'Creation returns 202 Accepted. Replaying the same body with the same Idempotency-Key returns the existing batch with 200 OK, without duplicate processing or billing.
Track and retrieve results
Poll every 10 seconds. Do not impose a 600-second global deadline on a 1,000-row batch.
import os
import time
import httpx
batch_id = "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
headers = {"X-API-Key": os.environ["TTH_API_KEY"]}
with httpx.Client(base_url="https://api.thetradehub.eu", headers=headers, timeout=30) as client:
while True:
response = client.get(f"/v1/classify/batch/{batch_id}")
response.raise_for_status()
batch = response.json()
print(batch["status"], batch["completed"], batch["failed"], batch["total"])
if batch["status"] in ("completed", "failed"):
break
time.sleep(10)
for item in batch.get("items", []):
if item["status"] == "completed":
print(item["id"], item["result"]["classification"]["recommended_code"])
else:
print(item["id"], item["status"], item.get("error"))| Level | Statuses |
|---|---|
| Parent batch | pending, processing, completed, failed |
| Row | completed, failed, timeout |
A completed batch may contain failed rows. Always inspect the completed and failed counters and then items.
Retry only failed rows
Create a new batch containing only rows with failed or timeout status. Keep their original id and payload, and use a new batch Idempotency-Key. Valid results from the first batch remain available and are not billed again.
For 429, honor Retry-After. For 502, 503 or 504, retry with progressive backoff. In both cases, reuse the original Idempotency-Key while retrying the same creation request.
Last updated on