API Reference: Batch — VideoRouter Docs

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

ParameterTypeDescription

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

ParameterTypeDescription

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

ParameterTypeDescription

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

ParameterTypeDescription

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.