> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt

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

# List batches

GET https://api.twelvelabs.io/v1.3/analyze/batches

Use this method to list all the batch objects in your account. The response sorts batches by creation date, with the newest batch first.


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

## Authentication

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

## Request

### Query parameters

- `page` (integer, optional, default: 1) — A number that identifies the page to retrieve. **Default**: `1`.
- `page_limit` (integer, optional, default: 10) — The number of items to return on each page. **Default**: `10`. **Max**: `50`.
- `status` (list of enum, optional) — Filter batches by status. Provide one or more values to include batches matching any of them. To send multiple values, repeat the `status` parameter: ``` status=processing&status=canceling ``` If you omit this parameter, the response includes batches in all statuses.
  - Allowed values: `pending`, `processing`, `canceling`, `canceled`, `completed`, `expired`
- `analysis_mode` (list of enum, optional) — Filter batches by analysis mode. Provide one or more values to include batches matching any of them. To send multiple values, repeat the `analysis_mode` parameter: ``` analysis_mode=general&analysis_mode=time_based_metadata ``` If you omit this parameter, the response includes batches in all analysis modes.
  - Allowed values: `general`, `time_based_metadata`

## Response

### 200

A list of batch objects.

- `data` (list of AnalyzeBatchStatusResponse, required) — An array of batch objects. Each object includes item counts for each item status.
- `page_info` (page_info, required) — An object that provides information about pagination.

## Errors

### 400 Bad Request Error

Invalid query parameters.

- `error` (ErrorResponseError, required)

## Types

### AnalyzeBatchStatusResponse

A batch object that includes item counts for each item status.

- `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.

### page_info

An object that provides information about pagination.

- `limit_per_page` (integer, optional) — The maximum number of items on each page.
- `page` (integer, optional) — The page you retrieved.
- `total_page` (integer, optional) — The total number of pages.
- `total_results` (integer, optional) — The total number of results.

### 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)

### 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`.

## Examples

**Response**

```json
{
  "data": [
    {
      "batch_id": "68f4ddaf8aaa60d33df0e800",
      "analysis_mode": "general",
      "model_name": "pegasus1.5",
      "status": "processing",
      "total_items": 100,
      "created_at": "2026-05-15T10:00:00Z",
      "expires_at": "2026-05-16T10:00:00Z",
      "queued_items": 30,
      "processing_items": 20,
      "ready_items": 50,
      "failed_items": 0,
      "canceled_items": 0
    },
    {
      "batch_id": "68f4ddaf8aaa60d33df0e7ff",
      "analysis_mode": "time_based_metadata",
      "model_name": "pegasus1.5",
      "status": "completed",
      "total_items": 50,
      "created_at": "2026-05-14T08:30:00Z",
      "expires_at": "2026-05-15T08:30:00Z",
      "queued_items": 0,
      "processing_items": 0,
      "ready_items": 48,
      "failed_items": 2,
      "canceled_items": 0,
      "completed_at": "2026-05-14T11:42:13Z"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "page": 1,
    "total_page": 1,
    "total_results": 2
  }
}
```

**SDK Code**

```python analyzeAsync_batches_list_example
import requests

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

querystring = {"status":"[\"processing\",\"canceling\"]","analysis_mode":"[\"general\",\"time_based_metadata\"]"}

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

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript analyzeAsync_batches_list_example
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D';
const options = {method: 'GET', 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_list_example
package main

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

func main() {

	url := "https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D"

	req, _ := http.NewRequest("GET", 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_list_example
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D")

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

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

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

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

HttpResponse<String> response = Unirest.get("https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D")
  .header("x-api-key", "<apiKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

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

```csharp analyzeAsync_batches_list_example
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift analyzeAsync_batches_list_example
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches?status=%5B%22processing%22%2C%22canceling%22%5D&analysis_mode=%5B%22general%22%2C%22time_based_metadata%22%5D")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
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()
```