Batch jobs (coming soon)

Process large request volumes asynchronously through the batch endpoints, with discounted pricing. Full workflow and quota limits are documented in the Batch guide. This page is the REST reference for every related endpoint.

Create a batch job

POST /v1/batches

Request body

input_file_idstringrequired

ID of an input file already uploaded to /v1/files with purpose=batch. One request object per line.

endpointenumrequired

Target endpoint path, e.g. /v1/chat/completions or /v1/embeddings.

completion_windowenumrequired

Completion window; currently "24h" is supported. Requests not completed within the window are marked expired.

metadataobjectoptional

Custom key/value pairs (up to 16) for tagging the source on the application side.

Response

Example — 201 created

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-xyz789",
  "status": "validating",
  "completion_window": "24h",
  "created_at": 1744828800,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 }
}

Retrieve a batch job

GET /v1/batches/{batch_id}

Path parameters

batch_idstring · pathrequired

Batch job ID.

Response fields (all states)

statusenum

validating / in_progress / finalizing / completed / failed / expired / cancelling / cancelled.

output_file_idstringoptional

Result file ID once finished; one response per line, each carrying custom_id.

error_file_idstringoptional

File ID containing details of failed requests.

request_countsobject

{ total, completed, failed } live progress counters.

created_at / in_progress_at / completed_at / failed_at / cancelled_atinteger

UNIX timestamps recorded at each status transition.

Cancel a batch job

POST /v1/batches/{batch_id}/cancel

Sets the status to cancelling; the scheduler stops dispatching new requests. Completed portions remain available via output_file_id. The final status becomes cancelled.

List batch jobs

GET /v1/batches

Query parameters

limitinteger · query20

Items per page, 1 – 100.

afterstring · queryoptional

Cursor pagination: pass the id of the last item on the previous page; results are ordered by creation time descending.