Status & download

GET /videos/3f1c…
{
  "videoId": "3f1c…",
  "status": "SUCCEEDED",
  "startedAt": 1790903142.5,
  "readyAt": 1790903205.0,
  "progress": { "planned": true, "chunksTotal": 4, "chunksDone": 4, "audioDone": true,
                "videoSeconds": 312.4, "topRendition": "1080p" },
  "downloadUrl": "https://…/download.mp4?…",
  "downloadExpiresInSeconds": 900,
  "posterUrl": "https://…/poster.jpg?…",
  "playbackUrl": "https://…/stream/3f1c…/1790910405/…/video.mp4",
  "posterPlaybackUrl": "https://…/stream/3f1c…/1790910405/…/poster.jpg",
  "playbackExpiresAt": 1790910405,
  "streamUrl": "https://…/stream/3f1c…/1790910405/…/master.m3u8",
  "streamExpiresAt": 1790910405
}

• Poll every 5–15 seconds while the status is SUBMITTED or RUNNING. Don't poll faster than once a second per video.
• downloadUrl is for downloading the file; it's valid for 15 minutes. Fetch the status again for a fresh link, and don't store the link.
• playbackUrl (every plan) and streamUrl (Pro and Scale) are for players: they stay seekable for their whole lifetime, twice the video's length (30 minutes to 24 hours), or ?linkTtl= seconds. See Build your own player.
• captions appears for videos made with captions: status, language and the file links.
• posterUrl is a still frame for thumbnails, also valid for 15 minutes. To pick a different frame or use your own image, see Thumbnails.
• progress shows chunks encoded out of the total, plus audio; videoSeconds is the result's length.
• Processing time is readyAt − startedAt (Unix seconds).
• edit / trim (when used) echo exactly how the video was cut, so you can check what was requested.

Listing your videos

GET /videos?limit=25
{ "videos": [ { "videoId": "9a8b…", "fileName": "Lesson 1", "createdAt": 1790903100, "state": "SUBMITTED", "clips": 3 }, … ],
  "nextToken": "eyJ2…" }

The newest videos come first. Pass nextToken back to get the next page. state only tells uploading from submitted. Once processing has ended, each video also has outcome (SUCCEEDED, FAILED, TIMED_OUT or ABORTED) and endedAt, and a succeeded one its durationSeconds and height (top quality), so you can show and sort a whole library without a status call per video. Call GET /videos/{id} for links and live progress. Videos made with captions have "captions": true.