> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/v1.3/api-reference/analyze-videos/batch-analysis/cancel-batch/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Cancel a batch

POST https://api.twelvelabs.io/v1.3/analyze/batches/{batch_id}/cancel

Use this method to request cancellation for a batch with the `pending` or `processing` status.

When you invoke this method, the platform performs the following steps:
- Cancels the items in the `queued` status.
- Finishes the analysis for the items in the `processing` status.

The batch status changes to `canceling` immediately, and to `canceled` after every item reaches `ready`, `failed`, or `canceled`. You are not billed for canceled or failed items.


Reference: https://docs.twelvelabs.io/api-reference/analyze-videos/batch-analysis/cancel-batch

## Authentication

- `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page.

## Request

### Path parameters

- `batch_id` (string, required) — The unique identifier of the batch.

## Response

### 202

The platform accepted the cancellation request. Items already in the `processing` status continue until processing finishes. The batch status is `canceling` until every item reaches `ready`, `failed`, or `canceled`, then becomes `canceled`. The response shows the batch state at the time of the request. To confirm the batch is fully canceled, use the [`GET`](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-status) method of the `/analyze/batches/{batch_id}` endpoint.

- `batch_id` (string, required) — The unique identifier of the batch. Use this value to retrieve the batch status or results.
- `analysis_mode` (enum, required) — The analysis mode applied to every item in this batch.
  - Allowed values: `general`, `time_based_metadata`
- `model_name` (string, required) — The model used for every item in this batch.
- `status` (enum, required) — The status of a batch. For the meaning of each value, see the [Batch statuses](/v1.3/api-reference/analyze-videos/batch-analysis/the-batch-object#batch-statuses) section on the **The batch object** page.
  - Allowed values: `pending`, `processing`, `canceling`, `canceled`, `completed`, `expired`
- `total_items` (integer, required) — The number of items submitted in the batch.
- `created_at` (string, required) — The date and time, in the RFC 3339 format, when the batch was created.
- `expires_at` (string, required) — The date and time, in the RFC 3339 format, when the batch expires (the `created_at` field value plus 24 hours). Unfinished items at expiration are canceled. Items that finished before then remain retrievable for 30 days after creation, when the batch and its results are deleted.
- `queued_items` (integer, required) — The number of items in the `queued` status.
- `processing_items` (integer, required) — The number of items in the `processing` status.
- `ready_items` (integer, required) — The number of items that completed successfully.
- `failed_items` (integer, required) — The number of items that failed.
- `canceled_items` (integer, required) — The number of items that were canceled, either because the batch was canceled while the item was in the `queued` status, or because the batch expired before the item finished processing.
- `completed_at` (string, optional) — The date and time, in the RFC 3339 format, when the batch status became `completed`. Present only when the status is `completed`.
- `canceled_at` (string, optional) — The date and time, in the RFC 3339 format, when the batch status became `canceled`. Present only when the status is `canceled`.
- `expired_at` (string, optional) — The date and time, in the RFC 3339 format, when the batch status became `expired`. Present only when the status is `expired`.
- `webhooks` (list of AnalyzeTaskWebhookInfo, optional) — The delivery status of each webhook endpoint for the batch completion notification. Present only after the platform sends the webhook notifications. To register webhooks, see the [Webhooks](/v1.3/docs/advanced/webhooks) page.

## Errors

### 404 Not Found Error

Batch not found.

- `error` (ErrorResponseError, required)

### 409 Conflict Error

The batch already reached a final status and cannot be canceled. The error code indicates which final status: `batch_completed` (status `completed`), `batch_canceled` (status `canceled`), or `batch_expired` (status `expired`).

- `error` (ErrorResponseError, required)

## Types

### AnalyzeTaskWebhookInfo

The delivery status of a webhook endpoint.

- `url` (string, required) — The URL of the webhook endpoint that received the delivery.
- `delivered` (boolean, required) — Indicates whether the platform successfully delivered the webhook.
- `attempts` (integer, required) — The total number of delivery attempts for this URL.
- `last_error` (string, optional) — The error message from the last failed delivery attempt. This field appears only when `delivered` is `false`.

### ErrorResponseError

- `code` (string, required) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, required) — A human-readable string describing the error, intended to be suitable for display in a user interface.
- `details` (map from string to any, optional) — Additional error details (optional)

## Examples

**Response**

```json
{
  "batch_id": "68f4ddaf8aaa60d33df0e800",
  "analysis_mode": "general",
  "model_name": "pegasus1.5",
  "status": "canceling",
  "total_items": 1000,
  "created_at": "2026-05-15T10:00:00Z",
  "expires_at": "2026-05-16T10:00:00Z",
  "queued_items": 0,
  "processing_items": 12,
  "ready_items": 480,
  "failed_items": 8,
  "canceled_items": 500
}
```

**SDK Code**

```python analyzeAsync_batches_cancel_example
import requests

url = "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel"

headers = {"x-api-key": "<apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript analyzeAsync_batches_cancel_example
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel';
const options = {method: 'POST', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go analyzeAsync_batches_cancel_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby analyzeAsync_batches_cancel_example
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java analyzeAsync_batches_cancel_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php analyzeAsync_batches_cancel_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp analyzeAsync_batches_cancel_example
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift analyzeAsync_batches_cancel_example
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/cancel")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```