Create batch

Create and start processing a batch from an uploaded file.

The batch will begin processing immediately. Use GET /batches/{batch_id} to monitor progress.

Request body

api_key_idstring uuid nullable

Attribute this batch to a specific API key (organization context only). The key must belong to the organization and be usable by the caller: one they created, or any org key for org owners/admins. The batch's spend counts against the selected key's usage limit and its usage is attributed to the key's creator. Members of a managed-keys organization must select a key when creating batches from the dashboard.

completion_windowstring required

The time window within which the batch should be processed (e.g., "24h", "1h"). The provider extension "background" selects no-SLA spare-capacity processing and requires the BackgroundInferenceUser role. Other allowed values are configured per instance.

endpointstring required

The endpoint to be used for all requests in the batch. Supported values are configured via batches.allowed_url_paths.

input_file_idstring required

The ID of an uploaded file that contains requests for the new batch

metadataobject nullable

Optional metadata (up to 16 key-value pairs)

Example request

{
  "completion_window": "24h",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123"
}

Response

Batch created and queued for processing.

cancelled_atinteger nullable

cancelling_atinteger nullable

completed_atinteger nullable

completion_windowstring required

The requested processing window, or "background" for no-SLA spare-capacity processing.

created_atinteger required

endpointstring required

error_file_idstring nullable

expired_atinteger nullable

expires_atinteger nullable

failed_atinteger nullable

finalizing_atinteger nullable

idstring required

in_progress_atinteger nullable

input_file_idstring required

metadataobject nullable

modelstring nullable

Model alias used by this batch's requests, or "mixed" when the input file spans multiple models. Cached on the batch at creation time; absent on batches created before this field existed.

object'batch' required

Object type - always "batch"

output_file_idstring nullable

statusstring required

Example response

{
  "completed_at": 1703190800,
  "completion_window": "24h",
  "created_at": 1703187200,
  "endpoint": "/v1/chat/completions",
  "id": "batch-abc123",
  "input_file_id": "file-abc123",
  "object": "batch",
  "output_file_id": "file-xyz789",
  "request_counts": {
    "completed": 98,
    "failed": 2,
    "total": 100
  },
  "status": "completed"
}

Create batch

Request body

Example request

Response

Example response

Changes