Sign in
batch

Retrieve a batch

Poll a batch. request_counts advances while it runs; once status is completed, failed, expired, or cancelled, download output_file_id and error_file_id. Poll every 30 to 60 seconds rather than holding a request open.

get/v1/batches/{batch_id}

Path parameters

batch_idstring required

The batch_ prefixed id returned when the batch was created.

Example:batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c

Identifies the batch to read.

Response

The batch.

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

Changed in 1 of the 3 revisions of this API.1