Vision AI Agents — Job Status & Polling Guide

Vision AI Agents processes video analysis and audience testing asynchronously.

When developers submit requests for video analysis or audience testing, the platform queues the job for processing and returns a status response.

Developers should poll the API periodically until the processing job completes.

Asynchronous Processing Model

Certain operations require processing time.

These include:

video ingest processing
intelligence analysis
audience testing

Instead of waiting for processing to complete during the request, the API returns a processing status.

Developers should periodically check job status using the polling endpoint.

Processing Workflow

The asynchronous processing workflow is shown below.

Submit Request
      ↓
Job Queued
      ↓
Processing Started
      ↓
Processing Complete
      ↓
Results Available

Once processing completes, the results can be retrieved through the appropriate API endpoint.

Example Processing Response

When a request is submitted, the API may return a response indicating that processing has started.

{
  "video_id": "vid_8392jf82",
  "status": "processing"
}

Processing Response Fields

Field	Type	Description
video_id	string	Unique identifier generated during video ingest
status	string	Current processing status of the job

Polling for Job Status

Developers should periodically query the status endpoint to determine whether processing has completed.

Endpoint

GET /api/video/status/{video_id}

Polling Request Parameters

Parameter	Type	Description
video_id	string	Video identifier returned from the ingest endpoint

Polling Request Example

GET /api/video/status/vid_8392jf82
Authorization: Bearer API_KEY

Status Response Example

{
  "video_id": "vid_8392jf82",
  "status": "completed"
}

Status Values

Status	Description
queued	Job has been received and is waiting in the processing queue
processing	The system is actively processing the job
completed	Processing finished and results are available
failed	Processing failed and the request should be retried or investigated

Retrieving Results

Once the status changes to completed, developers can retrieve results using the appropriate APIs.

Retrieve analysis results

POST /api/video/analyze

Retrieve search results

POST /api/search/query

Retrieve audience engagement insights

POST /api/audience/test

Recommended Polling Interval

Developers should avoid polling too frequently.

Recommended polling interval:

every 5–10 seconds

This prevents unnecessary API traffic while ensuring timely retrieval of results.

Best Practices

When implementing polling logic, developers should:

check the job status before requesting results
wait several seconds between polling attempts
stop polling once the status is completed
handle failed status responses gracefully

These practices improve system efficiency and reduce unnecessary API requests.

Example Developer Flow

A typical developer workflow using polling may look like this.

Upload Video
      ↓
Receive video_id
      ↓
Submit Analysis Request
      ↓
Poll Status Endpoint
      ↓
Status = Completed
      ↓
Retrieve Results