For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
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.
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.
Allowed values:
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.
