---
title: "Create a batch"
method: POST
path: "/analyze/batches"
tags: ["analyzeAsync > batches"]
---

# Create a batch

`POST /analyze/batches`

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.

## Headers

- `x-api-key` string, required

## Request body

- CreateAnalyzeBatchRequest — Defines a batch creation request. The `model_name` and `analysis_mode` fields apply to every item in the batch. You cannot override these fields per item. You can set every other field in the `defaults` object and override it per item.
  - `model_name` 'pegasus1.5', required — The video understanding model to use for every item in this batch. Batch analysis requires Pegasus 1.5.
  - `analysis_mode` 'general' | 'time_based_metadata', required — 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.
  - `defaults` BatchDefaults — 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.
    - `prompt` BatchPrompt — A structured prompt with `<@name>` placeholders for referencing images. Not supported when `analysis_mode` is `time_based_metadata`.
      - `input_text` string, required — The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources` (Example: `"Is there a <@tiger-1> in the video?"`). This text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window).
      - `media_sources` SMEMediaSource[] — Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources.
        - `name` string, required — A descriptive name for this media source.
        - `media_type` 'image', required — The media type. Only `image` is available.
        - `url` string, uri — A publicly accessible HTTPS URL of the image.
        - `asset_id` string — The unique identifier of an uploaded asset.
        - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
    - `response_format` AsyncResponseFormat — Controls the response format. When you omit this parameter, you receive unstructured text. - `json_schema`: Return structured JSON that conforms to your schema. - `segment_definitions`: Extract timestamped metadata with custom fields from your video. Requires `model_name` set to `pegasus1.5` and `analysis_mode` set to `time_based_metadata`.
      - `type` 'json_schema' | 'segment_definitions', required — The response format to use. - `json_schema`: Return structured JSON that conforms to your schema. - `segment_definitions`: Extract timestamped metadata with custom fields from your video. Requires `model_name` set to `pegasus1.5` and `analysis_mode` set to `time_based_metadata`.
      - `json_schema` AsyncResponseFormatJsonSchema — Contains the JSON schema that defines the response structure. The schema must adhere to the [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) specification. **Supported types** - `array` - `boolean` - `integer` - `null` - `number` - `object` - `string` - `timestamp` (Pegasus 1.5 only) **Supported constraints** | Type | Supported keywords | Notes | |------|-------------------|-------| | `integer` | `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`. | - `maximum`: Sets the highest allowed value (inclusive).<br/>- `exclusiveMaximum`: Sets the highest allowed value (exclusive).<br/>- `minimum`: Sets the lowest allowed value (inclusive).<br/>- `exclusiveMinimum`: Sets the lowest allowed value (exclusive).<br/>These constraints are supported only for the `integer` type. | | `string` | `pattern`, `format` | - `pattern`: A regular expression that the string must match.<br/>- `format`: Validates predefined formats. It accepts the following values: `uuid`, `date-time`, `date`, and `time`.<br/>See string limitations below. | | `object` | `properties`, `required` | - `properties`: Defines object properties and their schemas. - `required`: Specifies mandatory properties.<br/>See object limitations below. | | `array` | `items`, `minItems` | `minItems` accepts only `0` or `1`.<br/>See array limitations below. | | `timestamp` | `format` | `format` (required): Sets the output format. Accepted values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff`.<br/>See the **Timestamp type** section below. | **String limitations** When you use the `string` type: - The platform validates strings using only `pattern` and `format`. Including `minLength` or `maxLength` causes a 422 error: "String length constraints (minLength) are not supported." Remove these keywords from your schema. **Object limitations** When you use the `object` type: - The platform does not support the `additionalProperties` keyword. Including it causes a 422 error. Remove it from your schema. - The platform returns properties in declaration order. - Make the first property required. If the first property is optional, the platform moves the first required property to the beginning. **Array limitations** When you use the `array` type: - The platform does not support `uniqueItems` or `maxItems`. Including either keyword causes a 422 error. Remove them from your schema. **Constant and enumerated values** The `const` and `enum` keywords support the following types: - `boolean` - `null` - `number` - `string` **Schema composition** The platform supports only `anyOf` for [schema composition](https://json-schema.org/understanding-json-schema/reference/combining). **Annotations** The platform accepts but ignores JSON schema annotations like `title`, `$comments`, and `description`. **Subschema references** You can reference subschemas using `$ref` with these requirements: - Define subschemas within `$defs`. - Use valid URIs that point to the internal subschema. For details, see the [JSON Schema documentation on $defs](https://json-schema.org/understanding-json-schema/structuring#defs). **Timestamp type (Pegasus 1.5 only)** Declare a property as `{"type": "timestamp", "format": "<format>"}` to control the format of the returned value. The `format` field accepts the following values: | `format` | Example output | Notes | |----------|----------------|-------| | `seconds` | `10.5` | Returns a JSON number in seconds. | | `hh:mm:ss` | `"00:01:23"` | Rounded to the nearest second. Negative values are converted to `"00:00:00"`. | | `hh:mm:ss.fff` | `"00:01:23.500"` | Millisecond precision. | The type of the response depends on the value of the `format` field: `seconds` returns a JSON number, while `hh:mm:ss` and `hh:mm:ss.fff` return a JSON string. *Supported positions* You can declare `timestamp` fields at the top level of your schema or inside objects nested one level within an array: - Top level: `properties.<field_name>` - Inside an array: `properties.<array_field>.items.properties.<field_name>` Declaring `timestamp` outside these positions — deeper nesting, inside `oneOf` / `anyOf` / `allOf`, or inside `$ref` — is not supported and is rejected with HTTP 400. *Validation errors* When `format` is missing or invalid, the platform returns `400 parameter_invalid`: ``` response_format.json_schema.properties.<name>.format: format is required for timestamp type; allowed values: seconds, hh:mm:ss, hh:mm:ss.fff ``` **Reserved property names (`start_time` / `end_time`)** For Pegasus 1.5, properties named `start_time` or `end_time` in your response schema receive special type handling at any nesting depth (including inside array `items`). These are unrelated to the top-level `start_time` / `end_time` request parameters or `time_ranges`. The platform returns the value in a format determined by the declared type: *Allowed declarations:* | Declared type | Platform behavior | |---------------|-------------------| | `number` | Passes the value through without conversion. | | `integer` | Rounds the value to the nearest integer. | | `string` (no `format`) | Converts the value to the `hh:mm:ss.fff` format. | | `timestamp` with `format` | See the **Timestamp type** section above for the available formats. | *Rejected declarations (returns `400` error):* - `string` with any `format` keyword (`time`, `date-time`, `email`, `uri`, etc.) - `boolean` - `object` - `array` - `null` All other property names in your schema remain unconstrained by these rules. For other field names, use the `timestamp` type described above. **Response validation** Check the `FinishReason` field to verify your JSON response is complete: - When `FinishReason` is `stop`, the generation completed normally, and the JSON is valid and complete. - When `FinishReason` is `length`, the platform truncates the response at the maximum response length or the context window. This may result in truncated, invalid JSON that fails to parse.
      - `segment_definitions` SegmentDefinition[] — Define the types of segments to extract from your video. Minimum 1, maximum 20 definitions. The number of segment definitions affects billing. For details, see the [Frequently asked questions](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page.
        - `id` string, required — A unique identifier for this segment definition.
        - `description` string, required — Describe what this type of segment looks like in the video. The model uses this text to identify matching segments.
        - `fields` SegmentField[] — Custom fields to extract for each segment instance.
          - `name` string, required — The name of the field.
          - `type` 'string' | 'boolean' | 'number' | 'integer' | 'array' | 'timestamp', required — The data type of the field. When set to `timestamp`, the `format` property is required and controls the format of the returned value. Requires the `model_name` parameter set to `pegasus1.5`.
          - `description` string, required — Instructions that guide the model on what this field should contain and how to extract it from the video.
          - `format` 'seconds' | 'hh:mm:ss' | 'hh:mm:ss.fff' — The output format for `timestamp` fields. Required when `type` is `timestamp`. Must be omitted for any other type. | `format` | Example output | |----------|----------------| | `seconds` | `10.5` (JSON number in seconds) | | `hh:mm:ss` | `"00:01:23"` (rounded to the nearest second; negative values are converted to `"00:00:00"`) | | `hh:mm:ss.fff` | `"00:01:23.500"` (millisecond precision) | *Validation errors* The platform returns `400 parameter_invalid` (with field path `response_format.segment_definitions.fields.format`) when: - `type` is `timestamp` and `format` is missing, empty, or not one of the supported values. - `type` is not `timestamp` and `format` is set.
          - `enum` string[] — Allowed values for this field. Maximum 100 values. Not supported when `type` is `timestamp`.
          - `items` SegmentFieldItems — Required when `type` is `array`. Specifies the type of array elements. Not supported when `type` is `timestamp`.
            - `type` 'string' | 'number' | 'boolean' | 'integer', required
        - `media_sources` SMEMediaSource[] — Reference images that help the model identify segments. Maximum 4 sources.
          - `name` string, required — A descriptive name for this media source.
          - `media_type` 'image', required — The media type. Only `image` is available.
          - `url` string, uri — A publicly accessible HTTPS URL of the image.
          - `asset_id` string — The unique identifier of an uploaded asset.
          - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
        - `time_ranges` AnalyzeTimeRange[] — Time windows that limit segment extraction to specific parts of the video. Only supported for Pegasus 1.5 with `analysis_mode` set to `time_based_metadata`. <Note title="Notes"> - Each range must satisfy `end_time > start_time` with a minimum duration of `2` seconds. Both values must fall within the video duration. - Ranges within a single definition must not overlap. Touching boundaries are allowed (Example: `[0, 5]` and `[5, 10]`). - Mutually exclusive with the top-level `start_time` / `end_time` fields. - Mutually exclusive with `min_segment_duration` and `max_segment_duration`. - These time ranges control which portions of the `start_time`–`end_time` window are analyzed; the billable duration is always the full `start_time`–`end_time` span. </Note>
          - `start_time` number, double, required — The start of the window, as an absolute timestamp in seconds, based on the video's internal metadata. Must be less than `end_time` and within the video duration. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`.
          - `end_time` number, double, required — The end of the window, as an absolute timestamp in seconds, based on the video's internal metadata. Must be greater than `start_time` by at least `2` seconds and within the video duration. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`.
      - `segment_time_format` 'seconds' | 'hh:mm:ss' | 'hh:mm:ss.fff' — Set the output format for the automatic `start_time` and `end_time` keys returned on each segment. Requires the `type` parameter set to `segment_definitions` and the `model_name` parameter set to `pegasus1.5`. Omitting this parameter is equivalent to setting it to `seconds` — both return JSON numbers in seconds. | `segment_time_format` | Auto boundary output | |-----------------------|----------------------| | `seconds` (default) | JSON number in seconds (Example: `12.5`) | | `hh:mm:ss` | JSON string (Example: `"00:00:13"`) — rounded to the nearest second | | `hh:mm:ss.fff` | JSON string (Example: `"00:00:12.500"`) — millisecond precision | This parameter applies only to the automatic segment boundaries (`start_time` and `end_time`). Custom `timestamp` fields always use their own format, regardless of the value of this field.
    - `temperature` number, double — Controls the randomness of the text output. **Default:** 0.2 **Min:** 0 **Max:** 1
    - `max_tokens` integer — The maximum number of tokens to generate per item. The allowed range depends on the model and analysis mode (see the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint for the per-mode table).
    - `min_segment_duration` number, double — Minimum duration for each extracted segment, in seconds. Applies only when the `analysis_mode` field is `time_based_metadata`. **Min:** 2
    - `max_segment_duration` number, double — Maximum duration for each extracted segment, in seconds. Must be greater than or equal to the `min_segment_duration` field. Applies only when the `analysis_mode` field is `time_based_metadata`. **Min:** 2
    - `start_time` number, double — Start of the analysis window, in seconds, applied to every item. Use with `end_time` to analyze only the `[start_time, end_time)` portion of each video. <Note title="Notes"> - If omitted, defaults to `0`. - Must be less than `end_time`. - Mutually exclusive with `response_format.segment_definitions[].time_ranges`. </Note>
    - `end_time` number, double — End of the analysis window, in seconds, applied to every item. Use with `start_time` to analyze only the `[start_time, end_time)` portion of each video. <Note title="Notes"> - If omitted, defaults to the video duration. - Must be greater than `start_time`. - Mutually exclusive with `response_format.segment_definitions[].time_ranges`. </Note>
  - `requests` BatchItemRequest[], required — The analysis requests in the batch. Provide 1 to 1,000 requests, with a combined video duration of up to 2,000 hours.
    - `video` BatchVideoContext, required — Identifies the asset to analyze.
      - `type` 'asset_id', required — Set this field to `asset_id` to indicate that you're providing the video as an asset.
      - `asset_id` string, required — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
    - `custom_id` string — An optional identifier you set per item when you create the batch. Use this field to map batch results back to records in your system, for example, to correlate each result with the source video in your database. The platform stores this value unchanged. It appears in: - **Batch responses**: the array named `items` in the Create a batch response, and each line returned by the [`GET`](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-results) method of the `/analyze/batches/{batch_id}/results` endpoint. - **Task responses**: each batch request creates an analysis task. The `custom_id` field appears in the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint, the [`GET`](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks) method of the `/analyze/tasks` endpoint, and the `analyze.task.ready` and `analyze.task.failed` webhook payloads. **Format**: 1–64 characters. Alphanumeric, hyphens (`-`), and underscores (`_`) only. An empty string is rejected with a `400 Bad Request`. The value must be unique within a batch. Submitting two items with the same value in the `custom_id` field in the same batch returns a `400 Bad Request`. Items without a custom identifier still receive a unique task identifier generated by the platform in results.
    - `prompt` BatchPrompt — A structured prompt with `<@name>` placeholders for referencing images. Not supported when `analysis_mode` is `time_based_metadata`.
      - `input_text` string, required — The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources` (Example: `"Is there a <@tiger-1> in the video?"`). This text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window).
      - `media_sources` SMEMediaSource[] — Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources.
        - `name` string, required — A descriptive name for this media source.
        - `media_type` 'image', required — The media type. Only `image` is available.
        - `url` string, uri — A publicly accessible HTTPS URL of the image.
        - `asset_id` string — The unique identifier of an uploaded asset.
        - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
    - `response_format` AsyncResponseFormat — Controls the response format. When you omit this parameter, you receive unstructured text. - `json_schema`: Return structured JSON that conforms to your schema. - `segment_definitions`: Extract timestamped metadata with custom fields from your video. Requires `model_name` set to `pegasus1.5` and `analysis_mode` set to `time_based_metadata`.
      - `type` 'json_schema' | 'segment_definitions', required — The response format to use. - `json_schema`: Return structured JSON that conforms to your schema. - `segment_definitions`: Extract timestamped metadata with custom fields from your video. Requires `model_name` set to `pegasus1.5` and `analysis_mode` set to `time_based_metadata`.
      - `json_schema` AsyncResponseFormatJsonSchema — Contains the JSON schema that defines the response structure. The schema must adhere to the [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) specification. **Supported types** - `array` - `boolean` - `integer` - `null` - `number` - `object` - `string` - `timestamp` (Pegasus 1.5 only) **Supported constraints** | Type | Supported keywords | Notes | |------|-------------------|-------| | `integer` | `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`. | - `maximum`: Sets the highest allowed value (inclusive).<br/>- `exclusiveMaximum`: Sets the highest allowed value (exclusive).<br/>- `minimum`: Sets the lowest allowed value (inclusive).<br/>- `exclusiveMinimum`: Sets the lowest allowed value (exclusive).<br/>These constraints are supported only for the `integer` type. | | `string` | `pattern`, `format` | - `pattern`: A regular expression that the string must match.<br/>- `format`: Validates predefined formats. It accepts the following values: `uuid`, `date-time`, `date`, and `time`.<br/>See string limitations below. | | `object` | `properties`, `required` | - `properties`: Defines object properties and their schemas. - `required`: Specifies mandatory properties.<br/>See object limitations below. | | `array` | `items`, `minItems` | `minItems` accepts only `0` or `1`.<br/>See array limitations below. | | `timestamp` | `format` | `format` (required): Sets the output format. Accepted values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff`.<br/>See the **Timestamp type** section below. | **String limitations** When you use the `string` type: - The platform validates strings using only `pattern` and `format`. Including `minLength` or `maxLength` causes a 422 error: "String length constraints (minLength) are not supported." Remove these keywords from your schema. **Object limitations** When you use the `object` type: - The platform does not support the `additionalProperties` keyword. Including it causes a 422 error. Remove it from your schema. - The platform returns properties in declaration order. - Make the first property required. If the first property is optional, the platform moves the first required property to the beginning. **Array limitations** When you use the `array` type: - The platform does not support `uniqueItems` or `maxItems`. Including either keyword causes a 422 error. Remove them from your schema. **Constant and enumerated values** The `const` and `enum` keywords support the following types: - `boolean` - `null` - `number` - `string` **Schema composition** The platform supports only `anyOf` for [schema composition](https://json-schema.org/understanding-json-schema/reference/combining). **Annotations** The platform accepts but ignores JSON schema annotations like `title`, `$comments`, and `description`. **Subschema references** You can reference subschemas using `$ref` with these requirements: - Define subschemas within `$defs`. - Use valid URIs that point to the internal subschema. For details, see the [JSON Schema documentation on $defs](https://json-schema.org/understanding-json-schema/structuring#defs). **Timestamp type (Pegasus 1.5 only)** Declare a property as `{"type": "timestamp", "format": "<format>"}` to control the format of the returned value. The `format` field accepts the following values: | `format` | Example output | Notes | |----------|----------------|-------| | `seconds` | `10.5` | Returns a JSON number in seconds. | | `hh:mm:ss` | `"00:01:23"` | Rounded to the nearest second. Negative values are converted to `"00:00:00"`. | | `hh:mm:ss.fff` | `"00:01:23.500"` | Millisecond precision. | The type of the response depends on the value of the `format` field: `seconds` returns a JSON number, while `hh:mm:ss` and `hh:mm:ss.fff` return a JSON string. *Supported positions* You can declare `timestamp` fields at the top level of your schema or inside objects nested one level within an array: - Top level: `properties.<field_name>` - Inside an array: `properties.<array_field>.items.properties.<field_name>` Declaring `timestamp` outside these positions — deeper nesting, inside `oneOf` / `anyOf` / `allOf`, or inside `$ref` — is not supported and is rejected with HTTP 400. *Validation errors* When `format` is missing or invalid, the platform returns `400 parameter_invalid`: ``` response_format.json_schema.properties.<name>.format: format is required for timestamp type; allowed values: seconds, hh:mm:ss, hh:mm:ss.fff ``` **Reserved property names (`start_time` / `end_time`)** For Pegasus 1.5, properties named `start_time` or `end_time` in your response schema receive special type handling at any nesting depth (including inside array `items`). These are unrelated to the top-level `start_time` / `end_time` request parameters or `time_ranges`. The platform returns the value in a format determined by the declared type: *Allowed declarations:* | Declared type | Platform behavior | |---------------|-------------------| | `number` | Passes the value through without conversion. | | `integer` | Rounds the value to the nearest integer. | | `string` (no `format`) | Converts the value to the `hh:mm:ss.fff` format. | | `timestamp` with `format` | See the **Timestamp type** section above for the available formats. | *Rejected declarations (returns `400` error):* - `string` with any `format` keyword (`time`, `date-time`, `email`, `uri`, etc.) - `boolean` - `object` - `array` - `null` All other property names in your schema remain unconstrained by these rules. For other field names, use the `timestamp` type described above. **Response validation** Check the `FinishReason` field to verify your JSON response is complete: - When `FinishReason` is `stop`, the generation completed normally, and the JSON is valid and complete. - When `FinishReason` is `length`, the platform truncates the response at the maximum response length or the context window. This may result in truncated, invalid JSON that fails to parse.
      - `segment_definitions` SegmentDefinition[] — Define the types of segments to extract from your video. Minimum 1, maximum 20 definitions. The number of segment definitions affects billing. For details, see the [Frequently asked questions](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page.
        - `id` string, required — A unique identifier for this segment definition.
        - `description` string, required — Describe what this type of segment looks like in the video. The model uses this text to identify matching segments.
        - `fields` SegmentField[] — Custom fields to extract for each segment instance.
          - `name` string, required — The name of the field.
          - `type` 'string' | 'boolean' | 'number' | 'integer' | 'array' | 'timestamp', required — The data type of the field. When set to `timestamp`, the `format` property is required and controls the format of the returned value. Requires the `model_name` parameter set to `pegasus1.5`.
          - `description` string, required — Instructions that guide the model on what this field should contain and how to extract it from the video.
          - `format` 'seconds' | 'hh:mm:ss' | 'hh:mm:ss.fff' — The output format for `timestamp` fields. Required when `type` is `timestamp`. Must be omitted for any other type. | `format` | Example output | |----------|----------------| | `seconds` | `10.5` (JSON number in seconds) | | `hh:mm:ss` | `"00:01:23"` (rounded to the nearest second; negative values are converted to `"00:00:00"`) | | `hh:mm:ss.fff` | `"00:01:23.500"` (millisecond precision) | *Validation errors* The platform returns `400 parameter_invalid` (with field path `response_format.segment_definitions.fields.format`) when: - `type` is `timestamp` and `format` is missing, empty, or not one of the supported values. - `type` is not `timestamp` and `format` is set.
          - `enum` string[] — Allowed values for this field. Maximum 100 values. Not supported when `type` is `timestamp`.
          - `items` SegmentFieldItems — Required when `type` is `array`. Specifies the type of array elements. Not supported when `type` is `timestamp`.
            - `type` 'string' | 'number' | 'boolean' | 'integer', required
        - `media_sources` SMEMediaSource[] — Reference images that help the model identify segments. Maximum 4 sources.
          - `name` string, required — A descriptive name for this media source.
          - `media_type` 'image', required — The media type. Only `image` is available.
          - `url` string, uri — A publicly accessible HTTPS URL of the image.
          - `asset_id` string — The unique identifier of an uploaded asset.
          - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
        - `time_ranges` AnalyzeTimeRange[] — Time windows that limit segment extraction to specific parts of the video. Only supported for Pegasus 1.5 with `analysis_mode` set to `time_based_metadata`. <Note title="Notes"> - Each range must satisfy `end_time > start_time` with a minimum duration of `2` seconds. Both values must fall within the video duration. - Ranges within a single definition must not overlap. Touching boundaries are allowed (Example: `[0, 5]` and `[5, 10]`). - Mutually exclusive with the top-level `start_time` / `end_time` fields. - Mutually exclusive with `min_segment_duration` and `max_segment_duration`. - These time ranges control which portions of the `start_time`–`end_time` window are analyzed; the billable duration is always the full `start_time`–`end_time` span. </Note>
          - `start_time` number, double, required — The start of the window, as an absolute timestamp in seconds, based on the video's internal metadata. Must be less than `end_time` and within the video duration. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`.
          - `end_time` number, double, required — The end of the window, as an absolute timestamp in seconds, based on the video's internal metadata. Must be greater than `start_time` by at least `2` seconds and within the video duration. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`.
      - `segment_time_format` 'seconds' | 'hh:mm:ss' | 'hh:mm:ss.fff' — Set the output format for the automatic `start_time` and `end_time` keys returned on each segment. Requires the `type` parameter set to `segment_definitions` and the `model_name` parameter set to `pegasus1.5`. Omitting this parameter is equivalent to setting it to `seconds` — both return JSON numbers in seconds. | `segment_time_format` | Auto boundary output | |-----------------------|----------------------| | `seconds` (default) | JSON number in seconds (Example: `12.5`) | | `hh:mm:ss` | JSON string (Example: `"00:00:13"`) — rounded to the nearest second | | `hh:mm:ss.fff` | JSON string (Example: `"00:00:12.500"`) — millisecond precision | This parameter applies only to the automatic segment boundaries (`start_time` and `end_time`). Custom `timestamp` fields always use their own format, regardless of the value of this field.
    - `temperature` number, double — Controls the randomness of the text output. **Default:** 0.2 **Min:** 0 **Max:** 1
    - `max_tokens` integer — Override the `defaults.max_tokens` value for this item.
    - `min_segment_duration` number, double — Override the `defaults.min_segment_duration` value for this item.
    - `max_segment_duration` number, double — Override the `defaults.max_segment_duration` value for this item.
    - `start_time` number, double — Override the `defaults.start_time` value for this item.
    - `end_time` number, double — Override the `defaults.end_time` value for this item.

## Response `201`

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

- CreateAnalyzeBatchResponse — Response when creating a new batch.
  - `batch_id` string, required — The unique identifier of the batch.
  - `status` 'pending' | 'processing' | 'canceling' | 'canceled' | 'completed' | 'expired', 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.
  - `total_items` integer, required — The number of items submitted in the batch.
  - `created_at` string, date-time, required — The date and time, in the RFC 3339 format, when the batch was created.
  - `expires_at` string, date-time, 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.
  - `items` CreatedBatchItem[], required — 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.
    - `task_id` string, required — The unique task identifier generated by the platform for this item. 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 to retrieve the task's status and results.
    - `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`.

## Other responses

- `400` — Validation failure. The batch was not created. Possible causes include: - Malformed request bodies, or duplicate values in the `custom_id` field within the batch. - Missing required fields for the chosen analysis mode. - A missing video reference: the `requests.video` field is not provided, or its `type` is not `asset_id`. - A malformed value in the `requests.video.asset_id` field.
- `404` — A referenced asset does not exist, or you cannot access it. The batch was not created. Verify the `requests.video.asset_id` value and that the asset belongs to your account.
- `409` — A referenced asset exists but is not yet in the `ready` state. The batch was not created. Wait for the asset to reach the `ready` state, then resubmit the batch.
- `429` — You already have 5 active batches, or you exceeded the request rate limit.
- `503` — A cross-resource validation check against a downstream service (for example, asset metadata) failed temporarily. The batch was not created. Retry the request.
- `504` — The server did not finish creating the batch before its processing deadline. The batch was not created. Split the requests across smaller batches and retry.

---

[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/5dbd6e8473c9/schema)