---
title: "List the trailer's versions."
method: GET
path: "/trailers/{jobId}/versions"
tags: ["Trailer"]
---

# List the trailer's versions.

`GET /trailers/{jobId}/versions`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/trailers/{jobId}/versions`
- Auth: HTTP bearer

Returns every version of the trailer, newest first: its `number`, `stage` (preview, finished, current; `earlyLook` when an early look), when it was published, its master, the beats and takes it played, its `folder` of raw clips with where that copy stands (`archive.status`: pending, archiving, archived, partial, failed), and its zip (`zip.status`: none, queued, building, ready, failed; a signed `zip.url` while ready). Every time a trailer's master is published (a preview, an early look or the finished trailer) it is kept as a numbered version, so re-assembling a trailer never loses the master it replaces: the master, and for every beat in order the take each shot played (with its trim, and its finished copy on a finished trailer), the beat's cut before the film finish, its narration, speech, music, sound effects and text layer, and the finish it was laid with. Each version's cuts and takes are copied, untouched, into a folder of their own, one per beat (trailers/<trailer>/versions/<n>-<YYYYMMDD-HHMM>/beats/<NN>-<label>/), with a manifest.json, so a later re-render never loses the clips an earlier version played. Reading versions is free, and a zip of a version's clips is made on request, free. Scope: `story:read`.

## Response `200`

The trailer's versions.

- TrailerVersions
  - `jobId` string, required
  - `versions` TrailerVersionSummary[], required: Newest first.
    - `number` integer, required: The version's number: 1, 2, 3… in the order the trailer's masters were published.
    - `stage` 'preview' | 'finished' | 'current', required: The master's stage: a 480p `preview`, the `finished` trailer, or `current` (one recorded after the fact).
    - `earlyLook` boolean, required: True when the master was an early look (published while a newer cut was being assembled).
    - `publishedAt` string, date-time, required
    - `masterUrl` string, nullable, required
    - `masterDurationMs` integer, nullable, required
    - `masterResolution` string, nullable, required
    - `beatCount` integer, required: Beats the master played.
    - `takeCount` integer, required: Takes their cuts played.
    - `folder` string, required: The version's folder in storage: `trailers/<jobId>/versions/<n>-<YYYYMMDD-HHMM>/`.
    - `archive` object, required: Where the copy of its clips into the folder stands.
      - `status` 'pending' | 'archiving' | 'archived' | 'partial' | 'failed', required: `partial`: a clip was already gone when it was copied (the manifest lists it).
      - `files` integer, required
      - `missing` integer, required
      - `bytes` integer, nullable, required
      - `archivedAt` string, date-time, nullable, required
      - `error` string, nullable, required
    - `zip` VideoVersionZip, required: A version's zip: its manifest.json and every clip of its folder, stored as they are. Made on request, then kept.
      - `status` 'none' | 'queued' | 'building' | 'ready' | 'failed', required: `none` until asked for; `queued` / `building` while it is made; `ready`; `failed` (ask again).
      - `bytes` integer, nullable, required
      - `builtAt` string, date-time, nullable, required
      - `error` string, nullable, required: Why it could not be made (`failed` only).
      - `url` string, nullable, required: A signed download link while `ready` (it expires: read again for a fresh one).
      - `expiresAt` string, date-time, nullable, required
    - `label` string, required: "Version 3 · Finished 1080p · 2026-10-09 14:02 UTC".
  - `description` string, required

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The named project or source does not exist or is owned by another account.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)