Batches

The Batch API is the non-interactive async lane. Upload a file of one chat-completion request per line, create a batch over it, and Zumik runs each request through the real provider path and writes the results back as an output file you download.

Create a batch

POST https://api.zumik.ai/v1/batches

Parameters

Input file format

Each line is one request with a custom_id, the method, the target url, and the chat-completions body:

{"custom_id":"r1","method":"POST","url":"/v1/chat/completions","body":{"model":"code.fast","messages":[{"role":"user","content":"hi"}]}}
{"custom_id":"r2","method":"POST","url":"/v1/chat/completions","body":{"model":"auto.cheapest","messages":[{"role":"user","content":"yo"}]}}

Request

curl https://api.zumik.ai/v1/batches \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input_file_id":"file-9f2a...","endpoint":"/v1/chat/completions"}'

Response

{
  "id": "batch_01jy7n3q8v6m4k2x...",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-9f2a...",
  "completion_window": "24h",
  "status": "validating",
  "created_at": 1750000123,
  "metadata": {},
  "request_counts": { "total": 2, "completed": 0, "failed": 0 }
}

Create returns immediately with status: "validating"; the batch runs in the background. Poll retrieve until status is completed, then download the output_file_id content.

Output file format

One line per request, in the OpenAI batch-output shape:

{"id":"batch_req_01jy...","custom_id":"r1","response":{"status_code":200,"request_id":null,"body":{ "object":"chat.completion","...":"..." }},"error":null}

A failed request line carries a non-null error (code, message) and a null response.

Retrieve a batch

GET https://api.zumik.ai/v1/batches/{batch_id}

Returns the current batch object, including live request_counts and (once complete) output_file_id. 404 if it does not exist for this project.

Cancel a batch

POST https://api.zumik.ai/v1/batches/{batch_id}/cancel

Requests cancellation. A still-running batch (validating or in_progress) moves to cancelling, and the executor stops between requests, finalizing as cancelled with whatever it completed. A batch that already reached a terminal status keeps it. 404 if it does not exist for this project.

Limits

• A project may have at most 16 active batches at once; beyond that, create returns 429 / quota_exceeded.
• A single input file is capped at 50,000 requests; split larger jobs.
• Batches and their files are transient async I/O. Output files expire after a day, batch records after a week.

Errors

See the full error reference.