API ReferenceAnalyze 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. Poll this method until `status` is `ready` or `failed`. When `status` is `ready`, use the results from the response.

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.
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 null

The video source you provided. Only present for tasks that use direct video input (url, base64_string, or asset_id).

request_paramsobject or null
The request parameters for this task.
completed_atstringformat: "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.

resultobject

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

errorobject

A message 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.

Not set when status is ready and result.finish_reason is stop. Both Pegasus 1.5 and Pegasus 1.2 return this field when result.finish_reason is length.

webhookslist of objects

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 page for details.

Errors

404
Not Found Error