Swagger Petstore - OpenAPI 3.0
POST/batches/{batch_id}/cancel

Cancel a batch

Cancels an in-progress batch. The batch transitions to cancelling status for up to 10 minutes, then to cancelled with any partial results available in the output file. Returns the batch object with updated status.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter
batch_idstringrequired
The unique identifier of the batch to cancel.

1 status code
200Returns the batch object with status set to `cancelling`. The batch will transition to `cancelled` within 10 minutes.
idstringrequired
objectstringrequired
The object type, which is always `batch`.
Allowed:batch
endpointstringrequired
The OpenAI API endpoint used by the batch.
modelstringoptional
Model ID used to process the batch, like `gpt-5.6-sol`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models.
errorsobjectoptional
input_file_idstringrequired
The ID of the input file for the batch.
completion_windowstringrequired
The time frame within which the batch should be processed.
statusstringrequired
The current status of the batch.
Allowed:validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled
output_file_idstringoptional
The ID of the file containing the outputs of successfully executed requests.
error_file_idstringoptional
The ID of the file containing the outputs of requests with errors.
created_atintegerrequired
The Unix timestamp (in seconds) for when the batch was created.
in_progress_atintegeroptional
The Unix timestamp (in seconds) for when the batch started processing.
expires_atintegeroptional
The Unix timestamp (in seconds) for when the batch will expire.
finalizing_atintegeroptional
The Unix timestamp (in seconds) for when the batch started finalizing.
completed_atintegeroptional
The Unix timestamp (in seconds) for when the batch was completed.
failed_atintegeroptional
The Unix timestamp (in seconds) for when the batch failed.
expired_atintegeroptional
The Unix timestamp (in seconds) for when the batch expired.
cancelling_atintegeroptional
The Unix timestamp (in seconds) for when the batch started cancelling.
cancelled_atintegeroptional
The Unix timestamp (in seconds) for when the batch was cancelled.
request_countsobjectoptional
The request counts for different statuses within the batch.
usageobjectoptional
Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
metadataobjectoptional
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

Error handling

batch_id must identify an existing batch. Only batches with status in_progress or validating can be cancelled.