The AnalyzeAsyncClient.TasksClient class 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) and video segmentation with custom segment definitions. Both modes use Pegasus 1.5.

When to use this class:

• Generate custom text from your video using a prompt (general analysis)
• Extract timestamped metadata with custom segment definitions from your video
• Analyze videos longer than 1 hour, or a portion of a video up to 4 hours long
• Process videos asynchronously without blocking your application

Do not use this class for:

• Videos 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 identifier.
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:

def list(
    self,
    *,
    page: typing.Optional[int] = None,
    page_limit: typing.Optional[int] = None,
    status: typing.Optional[AnalyzeTaskStatus] = None,
    video_url: typing.Optional[str] = None,
    asset_id: typing.Optional[str] = None,
    analysis_mode: typing.Optional[TasksListRequestAnalysisMode] = None,
    request_options: typing.Optional[RequestOptions] = None,
) -> TasksListResponse:

Parameters:

Return value: Returns a TasksListResponse object.

The TasksListResponse class contains the following properties:

The PageInfo class 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 analysis modes: general analysis (prompt-based text generation) and video segmentation with custom segment definitions. Both modes use Pegasus 1.5.

On the Free plan, you have a total of 600 minutes (10 hours) shared across indexing, analysis, and segmentation. For details, see the Video hours and video count limits section.

Function signature and example:

def create(
    self,
    *,
    video: VideoContext,
    model_name: typing.Optional[CreateAsyncAnalyzeRequestModelName] = OMIT,
    custom_id: typing.Optional[str] = OMIT,
    prompt: typing.Optional[AnalyzeTextPrompt] = OMIT,
    prompt_v_2: typing.Optional[AnalyzePromptV2] = OMIT,
    analysis_mode: typing.Optional[CreateAsyncAnalyzeRequestAnalysisMode] = OMIT,
    temperature: typing.Optional[AnalyzeTemperature] = OMIT,
    max_tokens: typing.Optional[int] = OMIT,
    response_format: typing.Optional[AsyncResponseFormat] = OMIT,
    min_segment_duration: typing.Optional[float] = OMIT,
    max_segment_duration: typing.Optional[float] = OMIT,
    start_time: typing.Optional[float] = OMIT,
    end_time: typing.Optional[float] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> CreateAnalyzeTaskResponse:

Parameters:

VideoContext

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

The AsyncResponseFormat class contains the following properties:

AnalyzePromptV2

The AnalyzePromptV2 class defines a structured prompt with image references.

SegmentDefinition

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

SegmentField

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

SmeMediaSource

The SmeMediaSource class defines a reference image that provides visual context for segment identification. Provide exactly one of the url, asset_id, or base_64_string fields.

Return value: Returns a CreateAnalyzeTaskResponse object containing the task details.

The CreateAnalyzeTaskResponse class 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 are available. The error field describes the failure.

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

Function signature and example:

def retrieve(
    self,
    task_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> AnalyzeTaskResponse:

Parameters:

Return value: Returns an AnalyzeTaskResponse object containing the task status and results.

The AnalyzeTaskResponse class contains the following properties:

The AnalyzeTaskResponseVideoSource class contains the following properties:

The AnalyzeTaskResponseVideoSourceSystemMetadata class contains the following properties:

The AnalyzeTaskResponseRequestParams class contains the following properties:

The AnalyzeTaskResult class contains the following properties:

The AnalyzeTaskResultUsage class contains the following properties:

The AnalyzeTaskError class 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:

def delete(
    self,
    task_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> None:

Parameters:

Return value: Returns None. If successful, the platform returns a 204 No Content response.

API Reference: Delete an analysis task