Batch
For bulk work on the full 24-hour window — the OpenAI-compatible Files + Batches shape, so any OpenAI Batch
SDK client works with a one-line base_url change.
POST/v1/files
Requires the batch scope. multipart/form-data.
Parameters
filefileRequired. JSONL, one request object per line — max 200 MB, 50,000 lines.purposestring (form)Optional, default "batch" — currently the only accepted value.Example response
{
"id": "file_...",
"object": "file",
"bytes": 4096,
"created_at": 1731430000,
"filename": "batch_input.jsonl",
"purpose": "batch",
"status": "processed"
}GET/v1/files
Parameters
purposestring (query)Optional. Filter by batch/batch_output/batch_error.limitinteger (query)Optional, default 100.Example response
{ "object": "list", "data": [{ "...": "file object, same shape as POST /v1/files" }] }GET/v1/files/{id}
Returns the file object (metadata only — same shape as POST /v1/files's response). No parameters beyond the path id.
GET/v1/files/{id}/content
Raw bytes, Content-Type: application/x-ndjson — the response body IS the JSONL, not a JSON envelope. Works on the original input file, or the assembled output_file_id/error_file_id a finished batch points to.
POST/v1/batches
Requires the batch scope.
Parameters
input_file_idstringOne of this or requests is required (not both) — a file id from POST /v1/files.requestsarrayInline request objects — llmrouter extension, skips the file-upload step entirely. Non-empty list.endpointstringOptional, default "/v1/chat/completions" — the only supported value right now.completion_windowstringOptional, default "24h" ("15m" if service_tier:"flex" is set). Also accepts "1h"/"6h".metadataobjectOptional. Stored and echoed back verbatim, unvalidated.Each line (whether from the uploaded file or the inline requests array) needs a custom_id (unique within the batch), a url matching endpoint exactly, and a body object — the same fields /v1/chat/completions accepts.
Example response
{
"id": "batch_...",
"object": "batch",
"endpoint": "/v1/chat/completions",
"input_file_id": "file_...",
"completion_window": "24h",
"status": "in_progress",
"output_file_id": null,
"error_file_id": null,
"created_at": 1731430000,
"expires_at": 1731516400,
"completed_at": null,
"request_counts": { "total": 3, "completed": 0, "failed": 0 },
"metadata": null
}status is one of in_progress/cancelling/completed/failed/expired/cancelled — it starts in_progress immediately, there's no validating/queued phase. Once terminal with 20 or fewer lines, an inline results array is added too — otherwise fetch output_file_id/error_file_id via GET /v1/files/{id}/content.
GET/v1/batches
Parameters
limitinteger (query)Optional, default 20, clamped to [1, 100].afterstring (query)Optional. A batch id — a keyset cursor, returns batches created before it.Example response
{
"object": "list",
"data": [{ "...": "batch object" }],
"has_more": false,
"first_id": "batch_...",
"last_id": "batch_..."
}GET/v1/batches/{id}
Returns the batch object — same shape as POST /v1/batches's response. No parameters beyond the path id.
POST/v1/batches/{id}/cancel
No body. Releases every still-queued line's reservation and moves the batch to cancelling (lines already in flight are left to finish; the batch settles to cancelled once they're all terminal). A no-op returning the batch as-is if it's already terminal. Returns the batch object.