Sign in
batch

Create a batch

Start processing an uploaded input file. The batch is returned in validating; poll it until status is terminal. Every line must target /v1/chat/completions and name the same model, custom_id must be unique within the file, and stream: true is rejected. Billed per completed request at half the model's synchronous rate, including requests that complete before a cancel or expiry.

post/v1/batches

Request body

input_file_idstring required

Id of a file uploaded with purpose: batch.

endpoint'/v1/chat/completions' required

Must be /v1/chat/completions; every input line must use the same url.

completion_window'24h' required

Must be 24h. Requests not finished by then are expired, and the completed ones are still returned.

metadataobject

Up to 16 string pairs to tag the batch. Keys up to 64 characters, values up to 512.

Example request

{
  "input_file_id": "file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "job": "nightly-summaries"
  }
}

Response

The new batch, in validating.

idstring required

Batch identifier, batch_ prefixed.

objectstring required

Object type, always batch.

endpointstring required

The endpoint every line targets. Always /v1/chat/completions.

input_file_idstring required

The file the batch reads its requests from.

completion_windowstring required

Always 24h. Requests still queued when the window closes are written to the error file as batch_expired.

metadataobject nullable required

The key-value pairs you attached at creation, or null.

created_atinteger required

Unix timestamp (seconds) for when the batch was created.

status'validating' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled' required

Lifecycle state. completed, failed, expired, and cancelled are terminal. expired and cancelled batches still expose partial output.

modelstring

The model the batch runs on, once validation has read it from the input file.

output_file_idstring nullable required

File holding one BatchOutputLine per request the model answered. Set once the batch is terminal; null before that and when nothing completed.

error_file_idstring nullable required

File holding one BatchErrorLine per request that never got a model response. Set once the batch is terminal; null before that and when nothing failed.

in_progress_atinteger nullable required

Unix timestamp (seconds) for when processing started. null until it happens.

finalizing_atinteger nullable required

Unix timestamp (seconds) for when output files started being written. null until it happens.

completed_atinteger nullable required

Unix timestamp (seconds) for when the batch completed. null until it happens.

failed_atinteger nullable required

Unix timestamp (seconds) for when the batch failed. null until it happens.

expired_atinteger nullable required

Unix timestamp (seconds) for when the batch expired. null until it happens.

expires_atinteger nullable required

Unix timestamp (seconds) for when the completion window closes. null until it happens.

cancelling_atinteger nullable required

Unix timestamp (seconds) for when cancellation was requested. null until it happens.

cancelled_atinteger nullable required

Unix timestamp (seconds) for when cancellation finished. null until it happens.

Example response

{
  "id": "batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f",
  "completion_window": "24h",
  "metadata": {
    "job": "nightly-summaries"
  },
  "created_at": 1780000000,
  "status": "in_progress",
  "model": "morph-glm53flash",
  "output_file_id": null,
  "error_file_id": null,
  "in_progress_at": 1780000012,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "expires_at": 1780086400,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 2,
    "completed": 1,
    "failed": 0
  },
  "errors": null,
  "usage": {
    "input_tokens": 824,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 36,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 860
  }
}

Changes