Batches

Run offline or long-running jobs using KushRouter’s batch APIs. Batches let you upload a JSONL file of requests and process them asynchronously while receiving status updates and final results.

Unified batches API

Endpoint family root: /api/v1/batches

Create a batch

curl -X POST "https://api.kushrouter.com/api/v1/batches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_123",
    "metadata": { "label": "blog-drafts" },
    "settings": { "concurrency": 4 }
  }'

Key fields:

input_file_id – a file previously uploaded via the Files API (JSONL). Mutually exclusive with requests.
requests – inline array of request objects (each item resembles a request to your chosen endpoint). Mutually exclusive with input_file_id.
metadata – optional structured metadata stored with the batch.
settings.concurrency – optional concurrency hint.

Inline create example:

curl -X POST "https://api.kushrouter.com/api/v1/batches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "model": "gpt-4o-mini", "messages": [{"role":"user","content":"Say hi"}] }
    ]
  }'

List batches

curl -X GET "https://api.kushrouter.com/api/v1/batches" \
  -H "Authorization: Bearer $API_KEY"

Retrieve status

curl -X GET "https://api.kushrouter.com/api/v1/batches/batch_abc123" \
  -H "Authorization: Bearer $API_KEY"

Cancel

curl -X POST "https://api.kushrouter.com/api/v1/batches/batch_abc123/cancel" \
  -H "Authorization: Bearer $API_KEY"

Results (JSON)

curl -X GET "https://api.kushrouter.com/api/v1/batches/batch_abc123/results?offset=0&limit=100" \
  -H "Authorization: Bearer $API_KEY"

Returns { id, status, total, offset, limit, results[] } where each result has { index, status, result, usage?, error?, custom_id? }.

Export (NDJSON or ZIP)

curl -X GET "https://api.kushrouter.com/api/v1/batches/batch_abc123/export?format=ndjson&gzip=true&offset=0&limit=1000" \
  -H "Authorization: Bearer $API_KEY" \
  -o batch-results.ndjson.gz

format can be ndjson (default) or zip. Use gzip=true to gzip NDJSON.

OpenAI-compatible batches

We also expose OpenAI-compatible endpoints under /api/openai/v1/batches so third-party SDKs can operate without changes. Supported operations include create, list, retrieve, cancel, and item results.

curl -X POST "https://api.kushrouter.com/api/openai/v1/batches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/chat/completions"
  }'

Other routes:

GET /api/openai/v1/batches – list
GET /api/openai/v1/batches/{id} – retrieve
POST /api/openai/v1/batches/{id}/cancel – cancel
GET /api/openai/v1/batches/{id}/results?offset=&limit= – paginated item results

Monitoring progress

Batch status values: queued, processing, completed, cancelled, expired, failed.
Use the dashboard’s “Batches” tab for real-time progress, throughput, and retry counts.
NDJSON exports can be parsed using the examples in the developer docs.