Skip to main content

​
POST /v1/batches/:id/cancel

Cancel a batch that is currently being processed. Once cancelled, the batch cannot be resumed.
Cancelling a batch is permanent. Any requests that have already been processed will be included in the output file, but no new requests will be processed.

​
Authentication

Requires provider authentication headers: 
x-portkey-provider: openai
Authorization: Bearer YOUR_OPENAI_API_KEY

​
Request

​
Headers

​
x-portkey-provider
string
required
The provider to route the request to (e.g., openai)
​
Authorization
string
required
Bearer token for the provider API

​
Path Parameters

​
id
string
required
The ID of the batch to cancel

​
Response

​
id
string
The batch identifier
​
object
string
The object type, always “batch”
​
status
string
The status of the batch, which will be cancelling or cancelled
​
cancelled_at
integer
Unix timestamp of when the batch was cancelled
All other fields from the batch object are also returned.

​
Example

curl -X POST https://localhost:8787/v1/batches/batch_abc123/cancel \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

​
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": 1713894800,
  "in_progress_at": 1713894900,
  "cancelled_at": 1713895200,
  "completed_at": null,
  "request_counts": {
    "total": 100,
    "completed": 45,
    "failed": 0
  },
  "metadata": {
    "description": "Daily batch job"
  }
}

​
Cancellation Behavior

​
What Happens When You Cancel

  1. In Progress Requests: Requests currently being processed may complete
  2. Queued Requests: Requests that haven’t started processing are cancelled
  3. Output File: An output file is generated with all completed requests
  4. Billing: You’re only charged for completed requests

​
When Cancellation is Not Allowed

You cannot cancel a batch if its status is:
  • completed - Batch has already finished
  • failed - Batch has already failed
  • cancelled - Batch is already cancelled

​
Use Cases

Cancel batches that are taking longer than expected, allowing you to debug and resubmit with optimizations.
If requirements change mid-processing, cancel the batch and submit a new one with updated parameters.
If you detect an error in your input file after submission, cancel the batch to avoid wasting resources.

​
Best Practices

After cancelling a batch, wait a few seconds before retrieving it again to ensure the cancellation has been processed.
Always check if an output_file_id is available after cancellation - you may have partial results that are still useful.

Create Batch

Create a new batch

Retrieve Batch

Check batch status

List Batches

View all batches

Build docs developers (and LLMs) love

Get started for freeTalk to us