---
title: "Retrieve analysis task status and results"
method: GET
path: "/analyze/tasks/{task_id}"
tags: ["analyzeAsync > tasks"]
---

# Retrieve analysis task status and results

`GET /analyze/tasks/{task_id}`

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.

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

## Path parameters

- `task_id` string, required

## Headers

- `x-api-key` string, required

## Response `200`

Task status and results retrieved successfully

- AnalyzeTaskResponse — Represents the status and results of an analysis task.
  - `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
            - `type` string
        - `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`.

## Other responses

- `404` — Task not found

---

[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)