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

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

Use this method to retrieve the results for each item in a batch. You can call it while the batch has the `pending` or `processing` status.

Each result entry has a status. For details on each status, see the [Item statuses](/v1.3/api-reference/analyze-videos/batch-analysis/the-batch-object#item-statuses) section on the **The batch object** page.

Each result entry includes a task identifier in the `task_id` field. Use this value with the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint if you need the full analysis task response.

You can retrieve results for 30 days after batch creation.

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

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

The response is a JSON Lines (`application/jsonl`) stream. Each line is a JSON object containing one result entry for a batch item. Example body with four result entries: ```jsonl {"task_id":"68f4ddaf8aaa60d33df0e900","custom_id":"summary-001","status":"ready","data":{"generation_id":"gen_xyz789","data":"This video covers the keynote launch...","finish_reason":"stop","usage":{"output_tokens":150,"input_tokens":45}}} {"task_id":"68f4ddaf8aaa60d33df0e901","custom_id":"summary-002","status":"failed","error":{"code":"asset_unavailable","message":"The asset could not be read."}} {"task_id":"68f4ddaf8aaa60d33df0e902","custom_id":"summary-003","status":"processing"} {"task_id":"68f4ddaf8aaa60d33df0e903","custom_id":"summary-004","status":"queued"} ```

- `task_id` (string, required) — The unique task identifier generated by the platform for this item.
- `custom_id` (string, required, nullable) — The custom identifier you provided when you created the batch. If you did not provide one, this field is `null`.
- `status` (enum, required) — The status of a result entry. This field is different from the batch status. For the meaning of each value, see the [Item statuses](/v1.3/api-reference/analyze-videos/batch-analysis/the-batch-object#item-statuses) section on the **The batch object** page.
  - Allowed values: `queued`, `processing`, `ready`, `failed`, `canceled`
- `data` (AnalyzeTaskResult, optional) — Contains the analysis result for an item in the `ready` status. The analysis text is in this object's nested `data` field. The envelope uses the same schema as the `result` field in the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint.
- `error` (BatchItemError, optional) — Failure details for a single batch item.

## Errors

### 404 Not Found Error

Batch not found.

- `error` (ErrorResponseError, required)

## Types

### AnalyzeTaskResult

The analysis results for a completed task.

- `generation_id` (string, required) — The unique identifier for the generation session.
- `data` (string, required) — The generated text for this analysis task. The format depends on the `analysis_mode` used when creating the task: - **When `analysis_mode` is not set**: A plain-text string containing the generated text based on the prompt you provided. - **When `analysis_mode` is `time_based_metadata`**: A JSON-encoded string containing an object keyed by segment definition (the `id` field). Each key maps to an array of segment objects with the following fields: - `start_time` (number): The start time of the segment in seconds. - `end_time` (number): The end time of the segment in seconds. - `metadata` (object): The custom fields you defined in `segment_definitions[].fields`. The value of a `time_array` field is an array of event objects, one for each event inside the segment. Each event object contains `start_time` and `end_time`, which the platform adds automatically, plus the fields you declared in the `items.fields` array. - Segments are within the duration of the video, and events are within the duration of their segment. - The `min_segment_duration` and `max_segment_duration` values limit segments only, not the events inside them. - Event boundaries use the same format as segment boundaries, set by the `segment_time_format` value.
- `finish_reason` (enum, required) — When the task uses general analysis, `length` means the response reached the maximum response length or the context window. The partial output is in `data`, and a warning is in the task's `error` field. With video segmentation and a numeric `max_tokens`, the task fails when the analysis reaches either limit. This field is never `length` for a segmentation task. With `max_tokens` set to `unlimited`, this field is `stop` even when the output is incomplete.
  - Allowed values: `stop`, `length`
- `usage` (AnalyzeTaskResultUsage, required) — The number of tokens used in the generation.

### BatchItemError

Failure details for a single batch item.

- `message` (string, required) — A human-readable explanation of the failure.
- `code` (string, optional) — A machine-readable error code identifying the failure category.

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

### AnalyzeTaskResultUsage

The number of tokens used in the generation.

- `output_tokens` (integer, required) — The number of tokens in the generated text.
- `input_tokens` (integer, optional) — The number of tokens the input consumed. Together with `output_tokens`, this value must fit within the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window).

## Examples

### Ready result entry: analysis succeeded

**Response**

```json
{
  "task_id": "68f4ddaf8aaa60d33df0e900",
  "custom_id": "summary-001",
  "status": "ready",
  "data": {
    "generation_id": "gen_xyz789",
    "data": "This video covers the keynote launch of the new product line...",
    "finish_reason": "stop",
    "usage": {
      "output_tokens": 150,
      "input_tokens": 45
    }
  }
}
```

**SDK Code**

```python Ready result entry: analysis succeeded
import requests

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

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

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

print(response.json())
```

```javascript Ready result entry: analysis succeeded
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results';
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 Ready result entry: analysis succeeded
package main

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

func main() {

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

	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 Ready result entry: analysis succeeded
require 'uri'
require 'net/http'

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

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 Ready result entry: analysis succeeded
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/results")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Ready result entry: analysis succeeded
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

```csharp Ready result entry: analysis succeeded
using RestSharp;

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

```swift Ready result entry: analysis succeeded
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results")! 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()
```

### Failed result entry: analysis failed

**Response**

```json
{
  "task_id": "68f4ddaf8aaa60d33df0e901",
  "custom_id": "summary-002",
  "status": "failed",
  "error": {
    "message": "The asset could not be read.",
    "code": "asset_unavailable"
  }
}
```

**SDK Code**

```python Failed result entry: analysis failed
import requests

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

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

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

print(response.json())
```

```javascript Failed result entry: analysis failed
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results';
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 Failed result entry: analysis failed
package main

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

func main() {

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

	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 Failed result entry: analysis failed
require 'uri'
require 'net/http'

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

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 Failed result entry: analysis failed
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/results")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Failed result entry: analysis failed
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

```csharp Failed result entry: analysis failed
using RestSharp;

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

```swift Failed result entry: analysis failed
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results")! 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()
```

### Processing result entry: analysis in progress, no data or error yet

**Response**

```json
{
  "task_id": "68f4ddaf8aaa60d33df0e902",
  "custom_id": "summary-003",
  "status": "processing"
}
```

**SDK Code**

```python Processing result entry: analysis in progress, no data or error yet
import requests

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

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

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

print(response.json())
```

```javascript Processing result entry: analysis in progress, no data or error yet
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results';
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 Processing result entry: analysis in progress, no data or error yet
package main

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

func main() {

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

	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 Processing result entry: analysis in progress, no data or error yet
require 'uri'
require 'net/http'

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

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 Processing result entry: analysis in progress, no data or error yet
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/results")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Processing result entry: analysis in progress, no data or error yet
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

```csharp Processing result entry: analysis in progress, no data or error yet
using RestSharp;

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

```swift Processing result entry: analysis in progress, no data or error yet
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results")! 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()
```

### Queued result entry: analysis not started yet

**Response**

```json
{
  "task_id": "68f4ddaf8aaa60d33df0e903",
  "custom_id": "summary-004",
  "status": "queued"
}
```

**SDK Code**

```python Queued result entry: analysis not started yet
import requests

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

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

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

print(response.json())
```

```javascript Queued result entry: analysis not started yet
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results';
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 Queued result entry: analysis not started yet
package main

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

func main() {

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

	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 Queued result entry: analysis not started yet
require 'uri'
require 'net/http'

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

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 Queued result entry: analysis not started yet
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/results")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Queued result entry: analysis not started yet
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

```csharp Queued result entry: analysis not started yet
using RestSharp;

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

```swift Queued result entry: analysis not started yet
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results")! 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()
```

### Canceled result entry: canceled before analysis started

**Response**

```json
{
  "task_id": "68f4ddaf8aaa60d33df0e904",
  "custom_id": "summary-005",
  "status": "canceled"
}
```

**SDK Code**

```python Canceled result entry: canceled before analysis started
import requests

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

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

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

print(response.json())
```

```javascript Canceled result entry: canceled before analysis started
const url = 'https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results';
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 Canceled result entry: canceled before analysis started
package main

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

func main() {

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

	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 Canceled result entry: canceled before analysis started
require 'uri'
require 'net/http'

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

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 Canceled result entry: canceled before analysis started
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/results")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Canceled result entry: canceled before analysis started
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

```csharp Canceled result entry: canceled before analysis started
using RestSharp;

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

```swift Canceled result entry: canceled before analysis started
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches/68f4ddaf8aaa60d33df0e800/results")! 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()
```