Track progress

Poll job status and retrieve results from the Clipzy ML Engine API.

After creating a job, monitor it by polling the job status endpoint or by waiting for a webhook notification. This page covers polling, the processing stage sequence, and how to retrieve the final result.

Processing stages

A job moves through the following stages in order:

Stage	What happens
video_analysis	Frame extraction and scene detection.
audio_analysis	Beat detection, tempo, and audio fingerprinting.
motion_analysis	Camera motion, object tracking, and pacing analysis.
style_extraction	Color grading, cut rhythm, and transition style are extracted from the template.
style_application	Extracted style is mapped onto your footage.
rendering	Final video is encoded and written to storage.

current_stage is null when a job is queued and has not started processing yet.

Poll job status

Call GET /api/v1/jobs/{job_id} to check the current status, progress, and active stage.

Recommended polling interval: every 5 seconds. Polling more frequently does not speed up processing and increases unnecessary load.

cURL

curl http://localhost:8000/api/v1/jobs/job_xyz789abc123

Job status response

{
  "success": true,
  "data": {
    "job_id": "job_xyz789abc123",
    "video_id": "vid_abc123def456",
    "status": "processing",
    "progress_percent": 42,
    "current_stage": "motion_analysis",
    "created_at": "2024-04-05T10:30:00Z",
    "updated_at": "2024-04-05T10:37:05Z"
  }
}

Retrieve the result

When status is "completed", call GET /api/v1/jobs/{job_id}/result to get the output video URL and style data.

cURL

curl http://localhost:8000/api/v1/jobs/job_xyz789abc123/result

Result response

{
  "success": true,
  "message": "Job result retrieved",
  "data": {
    "job_id": "job_xyz789abc123",
    "status": "completed",
    "progress_percent": 100,
    "output_video_url": "file:///storage/job_xyz789abc123/output.mp4",
    "processing_time_seconds": 900.0,
    "style_json": {
      "version": "1.0",
      "color_grade": {
        "temperature": 10, "tint": 5, "saturation": 20,
        "contrast": 15, "highlights": 10, "shadows": -5
      },
      "aspect_ratio": "16:9",
      "frame_rate": 30,
      "cut_frequency": 3.5,
      "motion_intensity": 65,
      "zoom_usage": 30,
      "extraction_confidence": 0.92
    }
  }
}

style_json contains the Style DNA extracted during processing. See Style templates for how to interpret this object.

Calling /result on a job that is still processing or queued returns an error. Check that status is "completed" before fetching the result.

List all jobs

Use GET /api/v1/jobs to retrieve a paginated list of all your jobs.

cURL

curl "http://localhost:8000/api/v1/jobs?page=1&page_size=10"

List response

{
  "jobs": [
    {
      "job_id": "job_xyz789abc123",
      "status": "completed",
      "progress_percent": 100,
      "current_stage": null
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10
}

Query parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed).
page_size	integer	10	Number of jobs per page.

To iterate through all jobs, increment page until (page - 1) * page_size >= total.

Next steps

• Webhooks — receive a push notification instead of polling.
• Style templates — understand the style_json in the result.