Sign in
batch

Cancel a batch

Stop a validating or in_progress batch. It moves to cancelling while in-flight requests drain, then cancelled. Requests that already completed are kept in the output file and billed; the rest are written to the error file as batch_cancelled. Cancelling a terminal batch returns 400; cancelling one already cancelling is a no-op.

post/v1/batches/{batch_id}/cancel

Path parameters

batch_idstring required

The batch_ prefixed id of a batch that is still validating or in_progress.

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

Identifies the batch to cancel.

Response

The batch, now cancelling (or already terminal if it finished first).

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