Skip to navigation
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 result is available. The error field describes the failure.
  • canceled: The task was canceled. No result is available. The error field describes the cancellation reason, if available.

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

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

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. The ready, failed, and canceled statuses are final.

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.

batch_idstringOptionalformat: "^[0-9a-fA-F]{24}$"
The unique identifier of the batch that the task was created in. The platform returns this field only for tasks created as part of a batch.
video_sourceobject or nullOptional

The public video source associated with the task. When the video was uploaded using the POST method of the /tasks endpoint, the source type is video_id. Otherwise, the source type is url, base64_string, or asset_id.

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. When the task fails or is canceled, 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.
  • Task cancellation: status is canceled and a cancellation reason is available. A task newly canceled through the task cancellation endpoint has code set to user_canceled; canceling the task again does not change the reason.
  • 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. A canceled task can omit this field when no cancellation reason is available.

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