Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Cancel batch

POST
/batches/{batch_id}/cancel

Cancels an in-progress batch. The batch will be in status cancelling for up to 10 minutes, before changing to cancelled, where it will have partial results (if any) available in the output file.

Path Parameters
batch_id: string

The ID of the batch to cancel.

Returns
Batch object { id, completion_window, created_at, 19 more }
id: string
completion_window: string

The time frame within which the batch should be processed.

created_at: integer

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

formatunixtime
endpoint: string

The OpenAI API endpoint used by the batch.

input_file_id: string

The ID of the input file for the batch.

object: "batch"

The object type, which is always batch.

status: "validating" or "failed" or "in_progress" or 5 more

The current status of the batch.

One of the following:
"validating"
"failed"
"in_progress"
"finalizing"
"completed"
"expired"
"cancelling"
"cancelled"
cancelled_at: optional integer or null

The Unix timestamp (in seconds) for when the batch was cancelled.

formatunixtime
cancelling_at: optional integer or null

The Unix timestamp (in seconds) for when the batch started cancelling.

formatunixtime
completed_at: optional integer or null

The Unix timestamp (in seconds) for when the batch was completed.

formatunixtime
error_file_id: optional string or null

The ID of the file containing the outputs of requests with errors.

errors: optional object { data, object } or null
data: optional array of BatchError { code, line, message, param }
code: optional string

An error code identifying the error type.

line: optional integer or null

The line number of the input file where the error occurred, if applicable.

message: optional string

A human-readable message providing more details about the error.

param: optional string or null

The name of the parameter that caused the error, if applicable.

object: optional string

The object type, which is always list.

expired_at: optional integer or null

The Unix timestamp (in seconds) for when the batch expired.

formatunixtime
expires_at: optional integer or null

The Unix timestamp (in seconds) for when the batch will expire.

formatunixtime
failed_at: optional integer or null

The Unix timestamp (in seconds) for when the batch failed.

formatunixtime
finalizing_at: optional integer or null

The Unix timestamp (in seconds) for when the batch started finalizing.

formatunixtime
in_progress_at: optional integer or null

The Unix timestamp (in seconds) for when the batch started processing.

formatunixtime
metadata: optional Metadata or null

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.

model: optional string

Model ID used to process the batch, like gpt-6-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.

output_file_id: optional string or null

The ID of the file containing the outputs of successfully executed requests.

request_counts: optional BatchRequestCounts { completed, failed, total }

The request counts for different statuses within the batch.

completed: integer

Number of requests that have been completed successfully.

failed: integer

Number of requests that have failed.

total: integer

Total number of requests in the batch.

usage: optional BatchUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

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.

input_tokens: integer

The number of input tokens.

input_tokens_details: object { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: integer

The number of tokens that were retrieved from the cache. More on prompt caching.

output_tokens: integer

The number of output tokens.

output_tokens_details: object { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: integer

The number of reasoning tokens.

total_tokens: integer

The total number of tokens used.

Cancel batch

curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST
Response example
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711475133,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job"
  }
}
Returns Examples
Response example
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711475133,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job"
  }
}