Skip to main content
Process large datasets asynchronously at $0.08/1M tokens. Upload an NDJSON file (up to 5GB), start the job, poll for completion, and download results.

​
Workflow

1

Create job

POST /v1/batch — get a presigned upload URL
2

Upload file

POST your NDJSON file to the upload URL
3

Start processing

POST /v1/batch/{job_id}/start
4

Poll status

GET /v1/batch/{job_id} — until status is completed
5

Download results

GET /v1/batch/{job_id}/results — get a download URL

​
Input format

Upload an NDJSON file (one JSON object per line). Each line contains a text field: 
{"text": "I need help with billing"}
{"text": "The app keeps crashing"}
{"text": "How do I upgrade my plan?"}

​
1. Create job

POST /v1/batch Pass the classification config (same fields as /v1/classify). The text field is not included here — it comes from the uploaded file.

​
Request

FieldTypeRequiredDescription
labelsstring[]Yes*Classification labels (1–200)
classifierstringNoSaved classifier reference (alternative to labels)
descriptionsobjectNoPer-label descriptions
examplesobjectNoPer-label example texts
source_typestringNoContext for prompt tuning
modestringNosingle (default) or multi
thresholdnumberNoConfidence threshold for multi mode (default: 0.3)

​
Response (201)

{
  "job_id": "batch_a1b2c3d4e5f6g7h8",
  "upload_url": "https://s3.amazonaws.com/...",
  "upload_fields": {
    "key": "batch/user123/batch_a1b2.../input.ndjson",
    "policy": "...",
    "x-amz-signature": "..."
  },
  "input_key": "batch/user123/batch_a1b2.../input.ndjson"
}

​
Upload the file

Use the upload_url and upload_fields to upload your NDJSON file as a multipart form POST: 
curl -X POST "$UPLOAD_URL" \
  -F "key=$INPUT_KEY" \
  -F "policy=$POLICY" \
  -F "x-amz-signature=$SIGNATURE" \
  -F "file=@input.ndjson"

​
2. Start processing

POST /v1/batch/{job_id}/start Validates the uploaded file exists and starts background processing.
  • Only pending or failed jobs can be started
  • One active job per account at a time (409 if another is running)

​
Response (202)

{
  "job_id": "batch_a1b2c3d4e5f6g7h8",
  "status": "processing"
}

​
3. Poll status

GET /v1/batch/{job_id}

​
Response

{
  "job_id": "batch_a1b2c3d4e5f6g7h8",
  "status": "completed",
  "requests_total": 5000,
  "requests_completed": 5000,
  "requests_failed": 3,
  "estimated_tokens": 750000,
  "actual_tokens": 742150,
  "created_at": "2026-03-05T10:00:00Z",
  "started_at": "2026-03-05T10:00:05Z",
  "completed_at": "2026-03-05T10:08:32Z",
  "error": null
}
FieldTypeDescription
statusstringpending, processing, completed, or failed
requests_totalnumberTotal items in the input file
requests_completednumberSuccessfully processed items
requests_failednumberFailed items
estimated_tokensnumberEstimated token usage
actual_tokensnumberActual tokens used (null until complete)
errorstringError message if status is failed

​
4. Download results

GET /v1/batch/{job_id}/results Only available when status is completed.

​
Response

{
  "job_id": "batch_a1b2c3d4e5f6g7h8",
  "download_url": "https://s3.amazonaws.com/..."
}
The download URL points to an NDJSON file with one result per line: 
{"label": "billing", "confidence": 0.94, "tokens": 142}
{"label": "technical", "confidence": 0.87, "tokens": 138}
{"label": "sales", "confidence": 0.91, "tokens": 145}

​
5. Delete job

DELETE /v1/batch/{job_id} Deletes the job and its S3 files. Cannot delete jobs that are currently processing.

​
Response

{
  "job_id": "batch_a1b2c3d4e5f6g7h8",
  "deleted": true
}

​
Full example

# 1. Create job
JOB=$(curl -s -X POST https://api.classer.ai/v1/batch \
  -H "Authorization: Bearer $CLASSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["billing", "technical", "sales"],
    "mode": "single"
  }')

JOB_ID=$(echo $JOB | jq -r '.job_id')
UPLOAD_URL=$(echo $JOB | jq -r '.upload_url')

# 2. Upload NDJSON file (use upload_fields from response)
curl -X POST "$UPLOAD_URL" \
  -F "key=$(echo $JOB | jq -r '.upload_fields.key')" \
  -F "file=@input.ndjson"

# 3. Start processing
curl -X POST "https://api.classer.ai/v1/batch/$JOB_ID/start" \
  -H "Authorization: Bearer $CLASSER_API_KEY"

# 4. Poll until completed
while true; do
  STATUS=$(curl -s "https://api.classer.ai/v1/batch/$JOB_ID" \
    -H "Authorization: Bearer $CLASSER_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 5
done

# 5. Download results
DOWNLOAD_URL=$(curl -s "https://api.classer.ai/v1/batch/$JOB_ID/results" \
  -H "Authorization: Bearer $CLASSER_API_KEY" | jq -r '.download_url')
curl -o results.ndjson "$DOWNLOAD_URL"

​
Limits

LimitValue
Max file size5GB
Concurrent jobs1 per account
Pricing$0.08 / 1M tokens
Speed<15min P95