The AnalyzeAsync.Tasks interface provides methods to analyze videos asynchronously, generate text, and extract structured, timestamped segments. The platform supports two analysis modes: general analysis (prompt-based text generation) with both Pegasus 1.2 and Pegasus 1.5, and video segmentation with Pegasus 1.5.

When to use this interface:

• Generate custom text from your video using a prompt (Pegasus 1.2 only)
• Extract timestamped metadata with custom fields from your video (Pegasus 1.5 only)
• Analyze videos longer than 1 hour
• Process videos up to 2 hours
• Avoid blocking your application during video processing

Do not use this interface for:

• Videos under 1 hour for which you need immediate results or real-time streaming. Use the analyze method instead.

On the Free plan, analysis hours count toward a shared limit that also covers indexing - the number of segment definitions does not affect this limit. On paid plans, you pay based on how much video you process and how many segment definitions you include - see the Frequently asked questions page for examples.

Analyzing videos asynchronously requires three steps:

1. Create an analysis task using the create method. The platform returns a task ID.
2. Poll the status of the task using the retrieve method. Wait until the status is ready.
3. Retrieve the results from the response when the status is ready using the retrieve method.

Methods

List analysis tasks

Description: This method returns a list of the analysis tasks in your account. The platform returns your analysis tasks sorted by creation date, with the newest at the top of the list.

Function signature and example:

1
list(
2
    request?: TwelvelabsApi.analyzeAsync.TasksListRequest,
3
    requestOptions?: Tasks.RequestOptions
4
): core.HttpResponsePromise<TwelvelabsApi.analyzeAsync.TasksListResponse>

Parameters:

The TwelvelabsApi.analyzeAsync.TasksListRequest interface has the following properties:

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.analyzeAsync.TasksListResponse object.

The TwelvelabsApi.analyzeAsync.TasksListResponse interface contains the following properties:

The TwelvelabsApi.PageInfo interface contains the following properties:

For details about AnalyzeTaskResponse, see Retrieve task status and results.

API Reference: List async analysis tasks

Create an async analysis task

Description: This method asynchronously analyzes your videos. It supports two modes: general analysis (prompt-based text generation) with both Pegasus 1.2 and Pegasus 1.5, and video segmentation with Pegasus 1.5.

Function signature and example:

1
create(
2
    request: TwelvelabsApi.analyzeAsync.CreateAsyncAnalyzeRequest,
3
    requestOptions?: Tasks.RequestOptions
4
): core.HttpResponsePromise<TwelvelabsApi.CreateAnalyzeTaskResponse>

Parameters:

The TwelvelabsApi.analyzeAsync.CreateAsyncAnalyzeRequest interface has the following properties:

VideoContext

The TwelvelabsApi.VideoContext type specifies the source of the video. Provide exactly one of the following:

Set the type discriminator field to "url", "asset_id", or "base64_string" to indicate which source you are providing.

The AsyncResponseFormat class contains the following properties:

AnalyzePromptV2

The AnalyzePromptV2 interface defines a structured prompt with image references.

SegmentDefinition

The TwelvelabsApi.SegmentDefinition interface defines a type of segment to extract from the video.

SegmentField

The TwelvelabsApi.SegmentField interface defines a custom field to extract for each segment.

SmeMediaSource

The TwelvelabsApi.SmeMediaSource interface defines a reference image that provides visual context for segment identification. Provide exactly one of url, assetId, or base64String.

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.CreateAnalyzeTaskResponse object containing the task details.

The TwelvelabsApi.CreateAnalyzeTaskResponse interface contains the following properties:

API Reference: Create an async analysis task

Retrieve task status and results

Description: This method retrieves the status and results of an analysis task.

Task statuses:

• queued: The task is waiting to be processed.
• pending: The task is queued and waiting to start.
• processing: The platform is analyzing the video.
• ready: Processing is complete. Results are available in the response.
• failed: The task failed. No results were generated.

Call this method repeatedly until status is ready or failed. When status is ready, use the results from the response.

Function signature and example:

1
retrieve(
2
    taskId: string,
3
    requestOptions?: Tasks.RequestOptions
4
): core.HttpResponsePromise<TwelvelabsApi.AnalyzeTaskResponse>

Parameters:

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.AnalyzeTaskResponse object containing the task status and results.

The TwelvelabsApi.AnalyzeTaskResponse interface contains the following properties:

The TwelvelabsApi.AnalyzeTaskResponseVideoSource interface contains the following properties:

The TwelvelabsApi.AnalyzeTaskResponseVideoSourceSystemMetadata interface contains the following properties:

The TwelvelabsApi.AnalyzeTaskResponseRequestParams interface contains the following properties:

The TwelvelabsApi.AnalyzeTaskResult interface contains the following properties:

The TwelvelabsApi.AnalyzeTaskResultUsage interface contains the following properties:

The TwelvelabsApi.AnalyzeTaskError interface contains the following properties:

API Reference: Retrieve analysis task status and results

Delete an analysis task

Description: This method deletes an analysis task. You can only delete tasks that are not currently being processed.

Function signature and example:

1
delete(
2
    taskId: string,
3
    requestOptions?: Tasks.RequestOptions
4
): core.HttpResponsePromise<void>

Parameters:

Return value: Returns an HttpResponsePromise that resolves to void. If successful, the platform returns a 204 No Content response.

API Reference: Delete an analysis task