---
title: "Retrieve batch results"
method: GET
path: "/analyze/batches/{batch_id}/results"
tags: ["analyzeAsync > batches"]
---

# Retrieve batch results

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

## Path parameters

- `batch_id` string, required

## Headers

- `x-api-key` string, required

## 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"}
```

- BatchResultItem — One result entry per item. Result entries in the `ready` status include the `data` field. Result entries in the `failed` status include the `error` field. Result entries in the `queued`, `processing`, or `canceled` status include neither field.
  - `task_id` string, required — The unique task identifier generated by the platform for this item.
  - `custom_id` string, nullable, required — The custom identifier you provided when you created the batch. If you did not provide one, this field is `null`.
  - `status` 'queued' | 'processing' | 'ready' | 'failed' | 'canceled', 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.
  - `data` 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 the request's `segment_definitions[].fields`.
    - `finish_reason` 'stop' | 'length', required — The reason the generation stopped. - `stop`: The generation reached the end of the output text. - `length`: The response reached the maximum response length or the context window. For JSON responses, this may return truncated JSON that fails to parse.
    - `usage` AnalyzeTaskResultUsage, required — The number of tokens used in the generation.
      - `output_tokens` integer, required — The number of tokens in the generated text.
      - `input_tokens` integer — 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#context-window).
  - `error` BatchItemError — Failure details for a single batch item.
    - `code` string — A machine-readable error code identifying the failure category. Omitted until the per-item error catalog is wired through; until then, only `message` is guaranteed.
    - `message` string, required — A human-readable explanation of the failure.

## Other responses

- `404` — Batch not found.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/fd9d80e384a8/schema)