---
title: "List async analysis tasks"
method: GET
path: "/analyze/tasks"
tags: ["analyzeAsync > tasks"]
---

# List async analysis tasks

`GET /analyze/tasks`

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.

## Query parameters

- `page` integer
- `page_limit` integer
- `status` 'queued' | 'pending' | 'processing' | 'ready' | 'failed' — The current status of the analysis task.
- `video_url` string, uri
- `asset_id` string
- `video_id` string
- `analysis_mode` 'general' | 'time_based_metadata'

## Headers

- `x-api-key` string, required

## Response `200`

A list of analysis tasks.

- AnalyzeAsyncTasksListResponse200
  - `data` AnalyzeTaskResponse[], required — An array that contains up to `page_limit` analysis tasks.
    - `task_id` string, required — The unique identifier of the analysis task.
    - `custom_id` string, nullable, required — The identifier you provided in the `custom_id` field when you created the task, or `null` if you did not set one. This key is always present in the response.
    - `video_source` AnalyzeTaskResponseVideoSource — The video source you provided. Only present for tasks that use direct video input (`url`, `base64_string`, or `asset_id`).
      - `type` 'url' | 'base64_string' | 'asset_id' | 'video_id' — The type of video source.
      - `url` string, nullable — The video URL. Present when `type` is `url`.
      - `asset_id` string, nullable — The asset ID. Present when `type` is `asset_id`.
      - `video_id` string, nullable — The video ID. Present when `type` is `video_id`. Deprecated — use `asset_id` instead.
      - `index_id` string, nullable — The index ID associated with the video. Present when `type` is `video_id`. Deprecated — will be removed when Pegasus 1.2 is sunset.
      - `system_metadata` AnalyzeTaskResponseVideoSourceSystemMetadata — System-extracted video metadata. Present on a best-effort basis once the video has been processed.
        - `duration` number, double — The video duration in seconds.
    - `request_params` AnalyzeTaskResponseRequestParams — The request parameters for this task.
      - `analysis_mode` 'general' | 'time_based_metadata' — The analysis approach for this task.
      - `prompt` string, nullable — The natural-language prompt for this task. Present only when `analysis_mode` is `general` and the task was created with `prompt` (not `prompt_v2`). - [List](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks): Truncated to the first 30 characters. - [Retrieve](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results): Returns the full text.
      - `prompt_v2` AnalyzeTaskResponseRequestParamsPromptV2 — The structured prompt for this task. Present only when `analysis_mode` is `general` and the task was created with `prompt_v2`. When present, the response excludes the flat `prompt` field. - [List](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks): `input_text` is truncated to the first 30 characters. - [Retrieve](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results): Returns the full text.
        - `input_text` string — The prompt text. May contain `<@name>` placeholders that reference entries in `media_sources`.
        - `media_sources` AnalyzeTaskResponseRequestParamsPromptV2MediaSourcesItems[] — Reference images linked to `<@name>` placeholders in the prompt.
          - `name` string, required
          - `media_type` string, required
          - `url` string, uri — Present when the source was provided as a URL.
          - `asset_id` string — Present when the source was provided as an asset ID.
      - `response_format` AnalyzeTaskResponseRequestParamsResponseFormat — The response format for this task. Present only when the request included a response format.
        - `type` 'json_schema' | 'segment_definitions'
        - `json_schema` AnalyzeTaskResponseRequestParamsResponseFormatJsonSchema — The JSON schema for this task. Present only when `type` is `json_schema`. - [List](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks): Omitted. - [Retrieve](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results): Returns the full schema.
        - `segment_definitions` AnalyzeTaskResponseRequestParamsResponseFormatSegmentDefinitionsItems[] — The segment definitions for this task. Present only when `type` is `segment_definitions`. - [List](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks): Returns only the first element. - [Retrieve](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results): Returns the full array.
          - `id` string, required
          - `description` string, required
          - `fields` AnalyzeTaskResponseRequestParamsResponseFormatSegmentDefinitionsItemsFieldsItems[]
            - `name` string, required
            - `type` string, required
            - `description` string
            - `enum` string[]
            - `items` AnalyzeTaskResponseRequestParamsResponseFormatSegmentDefinitionsItemsFieldsItemsItems
              - …
          - `media_sources` AnalyzeTaskResponseRequestParamsResponseFormatSegmentDefinitionsItemsMediaSourcesItems[]
            - `name` string, required
            - `media_type` string, required
            - `url` string, uri
            - `asset_id` string
          - `time_ranges` AnalyzeTimeRange[] — The time ranges for this segment definition. Present only when the task was created with `time_ranges`.
            - `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`.
      - `temperature` number, double, nullable — The temperature value for this analysis.
      - `max_tokens` integer, nullable — The maximum response length you set, in tokens.
      - `min_segment_duration` number, double, nullable — The minimum segment duration you set, in seconds. Present when `analysis_mode` is `time_based_metadata`.
      - `max_segment_duration` number, double, nullable — The maximum segment duration you set, in seconds. Present when `analysis_mode` is `time_based_metadata`.
      - `start_time` number, double, nullable — The start of the analysis window, in seconds. Present only when the task was created with `start_time`.
      - `end_time` number, double, nullable — The end of the analysis window, in seconds. Present only when the task was created with `end_time`.
    - `status` 'queued' | 'pending' | 'processing' | 'ready' | 'failed', required — The current status of the analysis task.
    - `created_at` string, date-time, required — A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the analysis task was created.
    - `completed_at` string, date-time — A string representing the date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the analysis task was completed or failed. The platform returns this field only if `status` is `ready` or `failed`.
    - `result` 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`** (requires `model_name` set to `pegasus1.5`): 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` AnalyzeTaskError — A message attached to an analysis response. The platform uses this object in three cases: - **Task failure** — set on `AnalyzeTaskResponse.error` when `status` is `failed`. The `message` field describes the failure. - **Truncation: maximum response length reached** — set on the response `error` when `finish_reason` is `length` because `output_tokens` reached the requested `max_tokens` value. The `message` field advises increasing the `max_tokens` value. - **Truncation: context window reached** — set on the response `error` when `finish_reason` is `length` because the input and response reached the [context window](/v1.3/docs/concepts/models/pegasus#context-window). The `message` field advises reducing the input size or decreasing the `max_tokens` value. For truncation cases, the partial output is in `result.data` (async) or `data` (sync). Check `finish_reason` instead of parsing the message text.
      - `message` string, required — A human-readable message. One of: - **Failure** (async, `status: failed`): describes the failure reason, e.g., `"Video duration exceeds maximum allowed duration"`. - **Truncation: maximum response length reached** (`finish_reason: length`, `output_tokens >= max_tokens`): `"output truncated: the generation reached the configured max_tokens. The partial output is returned; raise max_tokens (up to 98304) if you need a longer response."`. - **Truncation: context window reached** (`finish_reason: length`, model stopped before reaching `max_tokens`): `"output truncated: combined input and output tokens reached the model's context limit. The partial output is returned; consider reducing input size (shorter prompt, smaller video clip, fewer media bindings) or lowering max_tokens."`. The exact text is not part of the contract — SDKs should not parse it.
    - `webhooks` AnalyzeTaskWebhookInfo[] — The delivery status of each webhook endpoint. The platform omits this field when no webhooks are configured. You can register webhooks through the Playground. See the [Webhooks](/v1.3/docs/advanced/webhooks) page for details.
      - `url` string, uri, required — The URL of the webhook endpoint that received the delivery.
      - `delivered` boolean, required — Indicates whether the platform successfully delivered the webhook.
      - `attempts` integer, required — The total number of delivery attempts for this URL.
      - `last_error` string — The error message from the last failed delivery attempt. This field appears only when `delivered` is `false`.
  - `page_info` PageInfo, required — An object that provides information about pagination.
    - `limit_per_page` integer — The maximum number of items on each page.
    - `page` integer — The page you retrieved.
    - `total_page` integer — The total number of pages.
    - `total_results` integer — The total number of results.

## Other responses

- `400` — The request has failed.

---

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