Create a batch | TwelveLabs

curl -X POST https://api.twelvelabs.io/v1.3/analyze/batches \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "model_name": "pegasus1.5",
  "analysis_mode": "general",
  "requests": [
    {
      "video": {
        "type": "asset_id",
        "asset_id": "6298d673f1090f1100476d4c"
      },
      "custom_id": "summary-001"
    },
    {
      "video": {
        "type": "asset_id",
        "asset_id": "6298d673f1090f1100476d4d"
      },
      "custom_id": "summary-002"
    },
    {
      "video": {
        "type": "asset_id",
        "asset_id": "6298d673f1090f1100476d4e"
      },
      "custom_id": "action-003",
      "prompt": {
        "input_text": "List all action items discussed."
      }
    }
  ],
  "defaults": {
    "prompt": {
      "input_text": "Generate a 3-sentence executive summary of this video."
    },
    "temperature": 0.2,
    "max_tokens": 4096
  }
}'

{
  "batch_id": "68f4ddaf8aaa60d33df0e800",
  "status": "pending",
  "total_items": 3,
  "created_at": "2026-05-15T10:00:00Z",
  "expires_at": "2026-05-16T10:00:00Z",
  "items": [
    {
      "task_id": "68f4ddaf8aaa60d33df0e900",
      "custom_id": "summary-001"
    },
    {
      "task_id": "68f4ddaf8aaa60d33df0e901",
      "custom_id": "summary-002"
    },
    {
      "task_id": "68f4ddaf8aaa60d33df0e902",
      "custom_id": "action-003"
    }
  ]
}

Model requirement

You must use Pegasus 1.5 for batch analysis. Set the model_name parameter to pegasus1.5.

When to use this method:

Run the same model and analysis settings across many videos.
Track a single batch instead of many individual analysis tasks.

Do not use this method for:

Single videos that require immediate results. Use the POST method of the /analyze endpoint instead.
Background processing of a single video. Use the POST method of the /analyze/tasks endpoint instead.

Retention and retry:

Batches expire 24 hours after creation. You can retrieve results for 30 days after creation.
If processing does not finish for some items in time, resubmit them in a new batch.

Limits:

Up to 1,000 requests per batch.
Up to 2,000 total content hours per batch.
Up to 5 active batches per account.

Use this method to submit many video analysis requests in a single call. Each request creates an analysis task. The response contains one batch identifier and one task identifier per request. Use the batch identifier to check progress and retrieve results. <Note title="Model requirement"> You must use Pegasus 1.5 for batch analysis. Set the `model_name` parameter to `pegasus1.5`. </Note> **When to use this method**: - Run the same model and analysis settings across many videos. - Track a single batch instead of many individual analysis tasks. **Do not use this method for**: - Single videos that require immediate results. Use the [`POST`](/v1.3/api-reference/analyze-videos/sync-analysis) method of the `/analyze` endpoint instead. - Background processing of a single video. Use the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint instead. **Retention and retry**: - Batches expire 24 hours after creation. You can retrieve results for 30 days after creation. - If processing does not finish for some items in time, resubmit them in a new batch. **Limits**: - Up to 1,000 requests per batch. - Up to 2,000 total content hours per batch. - Up to 5 active batches per account.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request

This endpoint expects an object.

model_nameenumRequired

The video understanding model to use for every item in this batch. Batch analysis requires Pegasus 1.5.

analysis_modeenumRequired

The analysis approach for every item in this batch.

general: Generate text from each video based on the prompt (the item’s prompt field if set, otherwise defaults.prompt). Supports structured JSON output by using json_schema in the response_format.type field.
time_based_metadata: Extract timestamped metadata by using segment_definitions in the response_format.type field.

Batches with mixed modes are not supported.

requestslist of objectsRequired

The analysis requests in the batch. Provide 1 to 1,000 requests, with a combined video duration of up to 2,000 hours.

defaultsobjectOptional

Default values applied to every item that does not override them. Every field is optional. Items in the requests array override these values. To override the prompt or response_format field, provide the full object on the item. You cannot change only some of its nested fields.

Response

The platform has created the batch and queued an analysis task for each request.

batch_idstring

The unique identifier of the batch.

statusenum

The status of a batch. For the meaning of each value, see the Batch statuses section on the The batch object page.

total_itemsinteger

The number of items submitted in the batch.

created_atstringformat: "date-time"

The date and time, in the RFC 3339 format, when the batch was created.

expires_atstringformat: "date-time"

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.

itemslist of objects

One entry per submitted item. Each entry pairs the unique task identifier generated by the platform with the custom identifier you provided when you created the batch.

Errors

400

Bad Request Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

503

Service Unavailable Error

504

Gateway Timeout Error