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

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 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 was completed or failed. The platform returns this field only if status is ready or failed.

resultobjectOptional

An object that contains the generated text and additional information. The platform returns this object only when status is ready. When the task fails, the response contains no result object, so generation_id and usage are absent.

errorobjectOptional

A message attached to the task response. The platform sets this field in the following cases:

  • Task failure: status is failed. The message field describes the failure reason. With video segmentation, a task can fail because the analysis reached the maximum response length or the context window before it could complete. The response contains no result object.
  • Truncation warning (general analysis): 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.

webhookslist of objectsOptional

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