---
title: "Episodes"
canonical: "https://docs.pbs.org/space/CDA/3053085/Episodes"
format: markdown
---
> Macro (toc)

## Overview

An episode resource is a container object belonging to a season. It can include multiple video asset types that relate to a single episode — full episode (max 1), clips (any number), previews (any number).

An episode can be uniquely identified by `id` or `slug`. If retrieving a resource by its slug, do not store the slug value as it may change. The `id` never changes.

## Endpoints

| Method | URL | Description |
| --- | --- | --- |
| GET | `/seasons/{season_id}/episodes/` | List episodes for a season |
| GET | `/episodes/{id|slug}/` | Get a single episode |
| POST | `/seasons/{season_id}/episodes/` | Create an episode |
| PATCH | `/episodes/{id}/` | Update an episode |
| DELETE | `/episodes/{id}/` | Delete an episode |
| GET | `/episodes/search/` | Search episodes |

> ℹ️ All URLs require the base endpoint prefix and a trailing slash. See [Resources](https://docs.pbs.org/space/CDA/3058039/Resources) for base endpoint and testing environment details.

## Episode Fields

Fields returned on GET requests and available for create/update operations.

| Field | Type | Description | Create | Update |
| --- | --- | --- | --- | --- |
| `type` | string | Object type | Required | Required |
| `id` | string (UUID) | Unique PBS content identifier | — | — |
| `ordinal` | integer | Episode number. Must be unique within its season (when combined with `segment`). | Required | Optional |
| `segment` | string | Segment identifier. Used with `ordinal` for multi-part episodes (e.g., Episode 3, Part 2). Returns empty string when not set. | Optional | Optional |
| `title` | string | Episode title (120 characters max) | Required | Optional |
| `title_sortable` | string | Title without leading articles, used for alphabetical sorting | Optional | Optional |
| `slug` | string | URL-friendly identifier. Must be unique across all episodes. **Set on create only** — cannot be updated. | Required | — |
| `tms_id` | string | Gracenote/TMS identifier, if available (e.g., `EP000031631056`). Read-only. | — | — |
| `description_short` | string | Short description (90 characters max) | Required | Optional |
| `description_long` | string | Long description (400 characters max) | Required | Optional |
| `premiered_on` | date (YYYY-MM-DD) | Original on-air or online broadcast date (no time) | Optional | Optional |
| `encored_on` | date (YYYY-MM-DD) | The on-air or online rebroadcast date (no time) | Optional | Optional |
| `nola` | string | NOLA code (National Online Locator for Archives, used for national programming only) | Optional | Optional |
| `language` | string | Language code (e.g., `en`) | Optional | Optional |
| `season` | object | Nested object containing details about the episode’s parent season. | — | — |
| `show` | object | Nested object containing details about the episode’s parent show. | — | — |
| `links` | list of objects | External links associated with the episode (e.g., Amazon, iTunes). Each object contains `value` (URL), `profile` (string), and `updated_at` (datetime). Read-only. | — | — |
| `metadatabankid` | string | Metadata Bank ID. Pass `null` to remove. Internal PBS use only. | — | Optional |
| `updated_at` | datetime | Timestamp of last update, in UTC (read-only) | — | — |

### Related Object Fields (in GET responses)

GET responses include nested **show** and **season** objects. When using the `fetch-related` parameter, **assets**, **collections**, **full_length_asset** (a single asset object for the full-length video, if one exists), and **season_links** (the parent season's external purchase links) are also included. See the example responses below for the structure of these nested objects, or refer to each resource's own page for full field documentation.

## List Episodes

`GET /seasons/{season_id}/episodes/`

Returns all episodes belonging to a season. Results are paginated.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `season_id` | string | PBS content ID of the season |

### Example Request

```
GET https://media.services.pbs.org/api/v1/seasons/{season_id}/episodes/
```

### Example Response

```
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "type": "episode",
      "id": "cc8b6404-c20c-42c9-9d77-35e7dbfae344",
      "attributes": {
        "ordinal": 20,
        "segment": "",
        "title": "Operation Space Station: Science and Survival",
        "title_sortable": "Operation Space Station: Science and Survival",
        "slug": "operation-space-station-science-and-survival-of9cgk",
        "tms_id": "EP000031631083",
        "description_short": "See how ingenuity and teamwork keep the crew alive and doing science 250 miles above Earth.",
        "description_long": "Witness life-or-death decisions 250 miles above Earth, as astronauts and Mission Control work together to survive moments of high danger on board humanity’s remarkable orbiting laboratory, the International Space Station.",
        "premiered_on": "2025-11-12",
        "encored_on": "2025-11-12",
        "nola": "005220",
        "language": "en",
        "updated_at": "2025-12-08T14:40:58.807577Z"
      },
      "links": {
        "self": "https://media.services.pbs.org/api/v1/episodes/cc8b6404-c20c-42c9-9d77-35e7dbfae344/",
        "assets": "https://media.services.pbs.org/api/v1/episodes/cc8b6404-c20c-42c9-9d77-35e7dbfae344/assets/",
        "collections": "https://media.services.pbs.org/api/v1/episodes/cc8b6404-c20c-42c9-9d77-35e7dbfae344/collections/"
      }
    },
    // ... additional episodes
  ],
  "meta": {
    "type": "collection",
    "filter": {
      "id": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?id=",
      "slug": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?slug=",
      "encored-on-gt": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?encored-on-gt=",
      "encored-on-lt": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?encored-on-lt=",
      "ordinal": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?ordinal="
    },
    "sort": {
      "title_sortable": {
        "asc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=title_sortable",
        "desc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=-title_sortable"
      },
      "ordinal": {
        "asc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=ordinal",
        "desc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=-ordinal"
      },
      "encored_on": {
        "asc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=encored_on",
        "desc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=-encored_on"
      },
      "premiered_on": {
        "asc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=premiered_on",
        "desc": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/?sort=-premiered_on"
      }
    },
    "pagination": {
      "per_page": 25,
      "count": 20
    }
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/episodes/",
    "first": null,
    "prev": null,
    "next": null,
    "last": null
  }
}
```

## Get Episode

`GET /episodes/{id|slug}/`

Returns a single episode by its ID or slug.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the episode |
| `slug` | string | URL slug of the episode (alternative to ID) |

### Example Request

```
GET https://media.services.pbs.org/api/v1/episodes/{id}/
```

### Example Response

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "episode",
    "id": "5a1ebaed-4600-47c6-86b3-fd0b378fc987",
    "attributes": {
      "ordinal": 1,
      "segment": "",
      "title": "What Are UFOs?",
      "title_sortable": "What Are UFOs?",
      "slug": "what-are-ufos-x0nz7l",
      "tms_id": "EP000031631056",
      "description_short": "Can science reveal the secrets of mysterious objects seen in our skies?",
      "description_long": "After decades in the shadows, UFOs are being studied seriously. Are they weather balloons, optical illusions, secret military technology? Or something else? Follow scientists as they try to unravel the mystery of the strangest objects in our skies.",
      "premiered_on": "2025-01-22",
      "encored_on": "2025-01-22",
      "nola": "005201",
      "language": "en",
      "updated_at": "2025-02-21T16:02:27.778865Z",
      "season": {
        "type": "season",
        "id": "e4948814-c240-4736-b61b-cda335a47165",
        "attributes": {
          "ordinal": 52,
          "title": "",
          "title_sortable": "",
          "updated_at": "2026-06-24T14:47:23.117148Z"
        },
        "links": {
          "self": "https://media.services.pbs.org/api/v1/seasons/e4948814-c240-4736-b61b-cda335a47165/"
        }
      },
      "show": {
        "type": "show",
        "id": "adfb2f9d-f61e-4613-ac58-ab3bde582afb",
        "attributes": {
          "title": "NOVA",
          "title_sortable": "NOVA",
          "slug": "nova",
          "display_episode_number": true,
          "updated_at": "2026-06-24T14:31:26.538876Z",
          "featured_preview": null
        },
        "links": {
          "self": "https://media.services.pbs.org/api/v1/shows/adfb2f9d-f61e-4613-ac58-ab3bde582afb/"
        }
      },
      "links": [
        {
          "value": "https://tv.apple.com/movie/what-are-ufos/umc.cmc.4y6v9hblixajzy7g6pcgqi1l1?itscg=30200&itsct=tv_box_link&mttnsubad=umc.cmc.4y6v9hblixajzy7g6pcgqi1l1",
          "profile": "itunes",
          "updated_at": "2025-02-21T16:02:27.461548Z"
        },
        {
          "value": "https://www.amazon.com/What-are-UFOs-Terri-Randall/dp/B0DMW141KW?crid=1PVR3YBWO5RYP&dib=eyJ2IjoiMSJ9.pL-K1aR1I5ErpU9f7JhMKeelJahu-5kywgG0mDD56vtvHLnKa5hVyckvI0lFgT4INfHg_lB50wWQ_cLR9tSKqUW3_6Td7-B8CGWGvWYJERsJLlus85NYtN65VT9ZzNp32tDOexDLbbYPWvGlnZOtTVNa17FYACdGUz6SULy03xZAX7I-50yOtOk_Zaad_8Hra8MUuhdVqkiFK1_COcnH1OH9exNufVf_6ip-ya1L8vM.rSW-ASeulZtCYY8SwD_zIAJ433iGT3s_lqAuQEZEw1A&dib_tag=se&keywords=What+are+UFOs%3F&qid=1738183321&s=instant-video&sprefix=what+are+ufos+%2Cinstant-video%2C89&sr=1-1&",
          "profile": "amazon",
          "updated_at": "2025-02-21T16:02:27.397678Z"
        }
      ]
    }
  },
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://media.services.pbs.org/api/v1/episodes/5a1ebaed-4600-47c6-86b3-fd0b378fc987/",
    "assets": "https://media.services.pbs.org/api/v1/episodes/5a1ebaed-4600-47c6-86b3-fd0b378fc987/assets/",
    "collections": "https://media.services.pbs.org/api/v1/episodes/5a1ebaed-4600-47c6-86b3-fd0b378fc987/collections/"
  }
}
```

## Create Episode

`POST /seasons/{season_id}/episodes/`

Creates a new episode within a season. A successful request returns **204 No Content**. The `Location` response header contains the URL of the newly created episode.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `season_id` | string | PBS content ID of the parent season |

### Required Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |

### Payload Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | string | Yes |  |
| `title` | string | Yes | 120 characters max |
| `ordinal` | integer | Auto-generated or can be assigned | Must be unique within the season (with segment) |
| `slug` | string | Auto-generated or can be assigned on create | Must be unique across all episodes. Set on create only. |
| `description_short` | string | Yes | 90 characters max |
| `description_long` | string | Yes | 400 characters max |
| `segment` | string | No | Segment identifier for multi-part episodes |
| `title_sortable` | string | No |  |
| `premiered_on` | date | No | YYYY-MM-DD format |
| `encored_on` | date | No | YYYY-MM-DD format |
| `nola` | string | No |  |
| `language` | string | No |  |

Fields not supported in create payload: `tms_id`, `links`

### Minimal Payload

```json
{
  "data": {
    "type": "episode",
    "attributes": {
      "title": "Episode Title",
      "description_short": "A brief description of the episode.",
        "description_long": "A more detailed description of the episode content."
    }
  }
}
```

### Full Payload

```json
{
  "data": {
    "type": "episode",
    "attributes": {
      "title": "Episode Title",
      "ordinal": 1,
      "slug": "episode-title",
      "description_short": "A brief description",
      "description_long": "A more detailed description of the episode content",
      "segment": "",
      "premiered_on": "2024-09-15",
      "encored_on": "2024-09-22",
      "nola": "ABCD1001",
      "language": "en"
    }
  }
}
```

### Response

**204 No Content** on success. Check the `Location` header for the new episode's URL.

## Update Episode

`PATCH /episodes/{id}/`

Updates an existing episode. A successful request returns **204 No Content**. Include only the fields you want to change.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the episode |

### Required Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |

### Payload Fields

The `slug` field cannot be updated.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | string | Yes |  |
| `id` | string | Yes |  |
| `title` | string | No | 120 characters max |
| `ordinal` | integer | No | Must be unique within the season (with segment) |
| `segment` | string | No | Segment identifier for multi-part episodes |
| `title_sortable` | string | No |  |
| `description_short` | string | No | 90 characters max |
| `description_long` | string | No | 400 characters max |
| `premiered_on` | date | No | YYYY-MM-DD format |
| `encored_on` | date | No | YYYY-MM-DD format |
| `nola` | string | No |  |
| `language` | string | No |  |
| `metadatabankid` | string | No | Metadata Bank ID. Pass `null` to remove. Internal PBS use only. |

Fields not supported in update payload: `slug`, `tms_id`, `links`

### Example Payload

```json
{
  "data": {
    "type": "episode",
    "id": "{episode_id}",
    "attributes": {
      "title": "Updated Episode Title",
      "description_short": "Updated short description"
    }
  }
}
```

### Moving an Episode to a Different Season

To move an episode from one season to another, include the target season's ID:

```json
{
  "data": {
    "type": "episode",
    "id": "{episode_id}",
    "attributes": {
      "season": "{target_season_id}"
    }
  }
}
```

### Converting an Episode to a Special

To convert an episode into a special, include the target show's ID in a `show` attribute:

```json
{
  "data": {
    "type": "episode",
    "id": "{episode_id}",
    "attributes": {
      "show": "{show_id}"
    }
  }
}
```

> 📝 When converting an episode to a special, the episode is removed from its season and becomes a special under the specified show.

### Response

**204 No Content** on success.

## Delete Episode

`DELETE /episodes/{id}/`

Permanently deletes the specified episode and all associated assets.

### URL Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | PBS content ID of the episode |

### Required Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |

### Response

**204 No Content** on success.

## Search Episodes

`GET /episodes/search/`

Full-text search across episode titles. The `query` parameter is required.

### Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search term — matches against episode title. Values must be URL-encoded. |
| `platform-slug` | string | No | Filter by platform slug |
| `platform-id` | string | No | Filter by platform ID |
| `page-size` | integer | No | Results per page (max 50) |
| `page` | integer | No | Page number |

### Example Request

```
GET https://media.services.pbs.org/api/v1/episodes/search/?query=civil%20war
```

## Query Parameters (List and Get)

These parameters can be used with the List and Get endpoints.

| Parameter | Type | Description |
| --- | --- | --- |
| `fetch-related` | flag | Include related objects in the response: `assets` (all asset types), `collections`, `full_length_asset` (convenience field returning just the full-length asset, or null), and `season_links` (the parent season's external purchase links). Returns the 10 most recent assets by encore date. |
| `encored_on_or_after` | date | Filter episodes with `encored_on` on or after this date (YYYY-MM-DD) |
| `encored_on_or_before` | date | Filter episodes with `encored_on` on or before this date (YYYY-MM-DD) |
| `id` | string | Filter by one or more episode IDs (repeat parameter for multiple) |

### Filtering by Multiple IDs

```
GET https://media.services.pbs.org/api/v1/episodes/?id={id1}&id={id2}&id={id3}
```

Returns 0 or more matching episodes. Recommend filtering no more than 50 IDs per request.