> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://beta.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://beta.docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server.

# Retrieve batch status

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

Use this method to monitor a batch. The response includes the current batch status and counts for queued, processing, ready, failed, and canceled items.

Poll this method until the batch reaches the `completed`, `canceled`, or `expired` status. To retrieve the results, call the [`GET`](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-results) method of the `/analyze/batches/{batch_id}/results` endpoint.

Do not treat the `completed` status as a success signal. It means processing has finished for every item, not that every analysis succeeded. To see how many items succeeded, failed, or were canceled, check the `ready_items`, `failed_items`, and `canceled_items` fields. A batch never has the `failed` status.

Reference: https://beta.docs.twelvelabs.io/api-reference/analyze-videos/batch-analysis/retrieve-batch-status

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

### 200

Batch status retrieved successfully. The response includes batch details and 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.

## Errors

### 404 Not Found Error

Batch not found.

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

### Batch in progress

**Request**

```json
{}
```

**Response**

```json
{
  "batch_id": "68f4ddaf8aaa60d33df0e800",
  "analysis_mode": "general",
  "model_name": "pegasus1.5",
  "status": "processing",
  "total_items": 4,
  "created_at": "2026-05-15T10:00:00Z",
  "expires_at": "2026-05-16T10:00:00Z",
  "queued_items": 1,
  "processing_items": 1,
  "ready_items": 2,
  "failed_items": 0,
  "canceled_items": 0
}
```

**SDK Code**

```python Batch in progress
import requests

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

payload = {}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.json())
```

```javascript Batch in progress
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800';
const options = {
  method: 'GET',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

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

```go Batch in progress
package main

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

func main() {

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

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

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

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

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

}
```

```ruby Batch in progress
require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

```java Batch in progress
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/68f4ddaf8aaa60d33df0e800")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php Batch in progress
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

```csharp Batch in progress
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Batch in progress
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

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

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()
```

### Batch completed

**Request**

```json
{}
```

**Response**

```json
{
  "batch_id": "68f4ddaf8aaa60d33df0e800",
  "analysis_mode": "general",
  "model_name": "pegasus1.5",
  "status": "processing",
  "total_items": 4,
  "created_at": "2026-05-15T10:00:00Z",
  "expires_at": "2026-05-16T10:00:00Z",
  "queued_items": 1,
  "processing_items": 1,
  "ready_items": 2,
  "failed_items": 0,
  "canceled_items": 0
}
```

**SDK Code**

```python Batch completed
import requests

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

payload = {}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.json())
```

```javascript Batch completed
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800';
const options = {
  method: 'GET',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

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

```go Batch completed
package main

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

func main() {

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

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

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

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

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

}
```

```ruby Batch completed
require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

```java Batch completed
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/68f4ddaf8aaa60d33df0e800")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

```csharp Batch completed
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Batch completed
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

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

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()
```