---
title: "List a project's episodes, versions and videos."
method: GET
path: "/story-projects/{projectId}/episodes"
tags: ["Projects"]
---

# List a project's episodes, versions and videos.

`GET /story-projects/{projectId}/episodes`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/story-projects/{projectId}/episodes`
- Auth: HTTP bearer

What the Writers Lab's Seasons tab and Videos page show, through their own cores: the project's seasons (named, with their episode counts), every episode — the ones the writer uploaded, started from the Series Bible or wrote in the app included — with its logline, format, genre, season, feed release and every version (with what has been made from it), the Series Bible's planned episodes joined against what is written, and the project's videos. An earlier or failed attempt at an episode is included and marked `supersededBy`, and left out of the season counts. `?season=N` narrows `episodes` and `plannedEpisodes` to one season. Cast lists are left out. The same read MCP `list_project_episodes` and `sleeperhit projects episodes` make. Read-only; costs no credits.

## Query parameters

- `season` integer

## Response `200`

The project's seasons, episodes, versions and videos.

- ProjectEpisodesResponse
  - `project` object, required
    - `id` string, required
    - `routeId` string, required
    - `name` string, required
  - `seasons` object[], required
    - `number` integer, required
    - `name` string, required
    - `episodeCount` integer, required: Episodes in it, earlier attempts left out.
  - `episodes` ProjectEpisode[], required: Oldest first within each season.
    - `scriptId` string, required
    - `routeId` string, required: The id in its Writers Lab URL.
    - `projectId` string, nullable, required: Its project, or null for a script in no project.
    - `title` string, required: The stored title.
    - `label` string, required: The name the episode is listed by everywhere, e.g. "S1E1 — The Return": its season and number with its title (a leading project name and episode code taken off); a script in no project is its title. Display only.
    - `slug` string, nullable, required: Its URL slug.
    - `logline` string, nullable, required: The writer's one-sentence logline — the same one Slug and the Writers Lab read and write.
    - `mediaType` string, nullable, required: `film` or `tv`.
    - `genre` string, nullable, required: Free text, in the writer's words.
    - `seasonNumber` integer, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `workspacePath` string, required: Where it opens in the Writers Lab, relative to the site origin.
    - `versions` WriterScriptVersion[], required: Newest first.
      - `scriptUploadId` string, required: The version's id: what coverage, overrides, table reads and exports take.
      - `versionNumber` integer, required
      - `title` string, required
      - `status` string, required: `draft` while it is being written; otherwise a locked version.
      - `parseStatus` string, nullable, required: Where the screenplay parse stands (`queued`, `parsing`, `complete`, `failed`); null when none ran.
      - `slug` string, nullable, required
      - `wordCount` integer, required
      - `pageCount` integer, nullable, required
      - `format` string, required: How it was written: text, fountain or fdx.
      - `createdAt` string, date-time, required
      - `counts` object, required: How much has been made from this version.
        - `coverageReports` integer, required
        - `tableReadJobs` integer, required
        - `pitchDeckJobs` integer, required
        - `visualizerJobs` integer, required
    - `release` object, nullable, required: The feed release of the plan that generated it, when there is one.
      - `status` string, required
      - `episodeNumber` integer, nullable, required
    - `supersededBy` string, nullable, required: Set when this is an earlier or failed attempt at an episode another script now stands for: that script's id.
  - `plannedEpisodes` object[], required: The Series Bible's episode map, joined against what is written.
    - `episodeId` string, required
    - `label` string, required
    - `title` string, required
    - `summary` string, required
    - `status` string, required
    - `seasonNumber` integer, required
    - `planIndex` integer, required
    - `writtenScriptId` string, nullable, required: The script that covers it; null when it has not been written.
  - `videos` object[], required
    - `id` string, required
    - `kind` 'trailer' | 'pitch-deck' | 'video', required
    - `title` string, required
    - `kindLabel` string, nullable, required
    - `description` string, nullable, required
    - `durationSeconds` number, nullable, required
    - `status` string, required
    - `scope` string, required: What it covers: an episode's title, "Season 2", "Project".
    - `scopeKind` 'episode' | 'season' | 'project' | 'null', nullable, required
    - `seasonNumber` integer, nullable, required
    - `videoUrl` string, nullable, required
    - `workspacePath` string, nullable, required
    - `createdAt` string, date-time, nullable, required
    - `updatedAt` string, date-time, required
  - `videosNote` string, nullable, required: Why `videos` is empty while the project has not finished development.
  - `workspacePath` string, required

## Other responses

- `400`: Request payload failed validation. The error message names the offending field.
- `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)