Get Video Status

`GET /api/videos/{id}/status`

Check the processing status of a video. Poll this endpoint to track progress.

Path Parameters

Parameter	Type	Description
`id`	string	The video ID from the submit endpoint

Status Flow

downloading → uploading → transcribing → analyzing → generating_clips → completed
                                                                       ↘ failed

Example

curl https://api.scalereach.ai/api/videos/UThwmCZb75JYZi4UP9rOX/status \
  -H "Authorization: Bearer sr_live_YOUR_KEY"

import requests, time

video_id = "UThwmCZb75JYZi4UP9rOX"
headers = {"Authorization": "Bearer sr_live_YOUR_KEY"}

while True:
    r = requests.get(f"https://api.scalereach.ai/api/videos/{video_id}/status", headers=headers)
    data = r.json()
    status = data["video"]["status"]
    progress = data.get("job", {}).get("progress", 0)
    print(f"Status: {status} ({progress}%)")
    if status in ("completed", "failed"):
        break
    time.sleep(15)

Response `200`

{
  "video": {
    "id": "UThwmCZb75JYZi4UP9rOX",
    "status": "analyzing",
    "title": "How Steve Jobs saved Apple from BANKRUPTCY?",
    "duration": 1950,
    "errorMessage": null
  },
  "job": {
    "id": "video-UThwmCZb75JYZi4UP9rOX",
    "state": "active",
    "progress": 70
  }
}

Poll every 10-15 seconds. A typical 30-minute video takes 3-5 minutes to fully process.

What each status means

Status	What ScaleReach is doing
`downloading`	Fetching the source video from the link you submitted.
`uploading`	Storing the downloaded video so it can be processed.
`transcribing`	Turning the speech into a timed transcript.
`analyzing`	Scoring the transcript and finding the strongest moments.
`generating_clips`	Cutting, reframing and captioning each selected clip.
`completed`	All clips are ready. Fetch them with `GET /api/videos/{id}/clips`.
`failed`	Processing stopped. Read `video.errorMessage` for the reason.

The response has two parts. video is the video record: its id, status, title, duration, and an errorMessage that is null unless something went wrong. job describes the background processing job: state is the job state (for example active), and progress is a number from 0 to 100. The job can be missing once a video has finished, so read job.progress defensively, as the Python example above does with .get().

Treat completed and failed as the only final states. Everything else means the video is still moving through the pipeline, so keep polling.

Errors

Status	When it happens
`401`	The API key is missing, invalid or expired.
`403`	The video belongs to a workspace you are not a member of.
`404`	No video exists with that ID.
`500`	The status could not be read. Retry after a few seconds.

Polling tips

Poll every 10 to 15 seconds. Polling faster does not make processing quicker and can run into rate limits (429).
Set an overall timeout in your script, for example 30 minutes, so a stuck job does not poll forever.
Very long videos take longer than the 3 to 5 minutes quoted for a 30-minute video, so scale your timeout with duration.
If you would rather not poll, the MCP integrations let an assistant check the status for you when you ask.

Failed videos

When the status is failed, video.errorMessage holds the reason. Check that the source link still opens, is public and is not age-restricted, then fix the cause, then submit the video again. A failed video does not produce clips.