Models and searchAnalyze and segment videos

Retrieve analysis task status and results

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. - `canceled`: The task was canceled. The task cannot become `ready`, and no result is available. Poll this method until `status` is `ready`, `failed`, or `canceled`. When `status` is `ready`, use the results from the response. The platform does not emit an `analyze.task.canceled` webhook. For an individual task without a terminal task webhook, poll this method with exponential backoff and jitter until the task reaches a terminal status. For a batch-owned task, prefer the parent batch's `analyze.batch.canceled` or `analyze.batch.expired` webhook and retrieve the batch status and results instead of polling every item.

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Path parameters

task_idstringRequired
The unique identifier of the analysis task.

Response

Task status and results retrieved successfully
task_idstring
The unique identifier of the analysis task.
custom_idstring or null

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.

statusenum

The current status of the analysis task.

ready, failed, and canceled are terminal.

created_atstringformat: "date-time"

A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the analysis task was created.

video_sourceobject or nullOptional
The video source you provided.
request_paramsobject or nullOptional
The request parameters for this task.
completed_atstringOptionalformat: "date-time"

A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the analysis task completed, failed, or was canceled. The platform returns this field only if status is ready, failed, or canceled.

resultobjectOptional

An object that contains the generated text and additional information. The platform returns this object only when status is ready.

errorobjectOptional

A condition attached to the task response. The platform sets this field in two cases:

  • Task failure: status is failed. The message field describes the failure reason.
  • Truncation warning: status is ready and result.finish_reason is length. The message field describes the truncation cause (either the maximum response length was reached or the context window was reached). The partial output is in result.data.

Check status before treating this field as a failure. This field is not set when status is ready and result.finish_reason is stop; it is set when result.finish_reason is length.

webhookslist of objectsOptional

The delivery status of each configured webhook endpoint. The platform omits this field when no webhooks are configured. See the Webhooks page for supported events, registration, and reconciliation guidance.

Errors

404
Not Found Error