# Episodes

> A series’ episodes: titles, overviews, air dates, runtime and ratings.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

Request: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}/episodes`

Episodes come in order: season, then episode number. `season` keeps one season.

`group=season` returns a summary instead of episodes: one row per season with the episode count, dates and rating. Draw a season list from it without loading every episode.

Specials come as season `0` and are marked `special: true`. A movie has no episodes: the response is `total: 0` with empty `items`, which is not an error.

## Path parameters

- `type` (string, required) — The catalog the ID comes from: IMDb, Kinopoisk, TMDB (movie or series) or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, required) — The ID in that catalog. IMDb IDs are `tt` followed by digits (`tt1375666`); the others are digits (`447301`).

## Query parameters

- `season` (integer) — Season number. `0` means specials.
  Default: every season. Example: `season=1`.
- `group` (enum) — `season` gives a per-season summary instead of episodes. `none` gives episodes.
  Values: `season`, `none`.
  Default: `none`.
- `lang` (ru | en) — Keep one language in the response. Without it, text fields come in `_ru` and `_en` pairs. More in [Response languages](https://kinodata.space/en/docs/languages.md).
  Example: `lang=en`.
- `limit` (integer) — How many episodes to return, up to 1000.
  Default: 1000.
- `offset` (integer) — How many episodes to skip.
  Default: 0.

## Response fields

- `items` (array) — Episodes.
  - `season`, `episode` (integer) — Season and episode number.
  - `special` (boolean) — A special.
  - `imdb_id` (string | null) — The episode’s IMDb ID.
  - `air_date` (string | null) — Air date, `YYYY-MM-DD`.
  - `name_ru`, `name_en` (string | null) — Episode title.
  - `name_original` (string | null) — Title in the original language, when it is neither Russian nor English.
  - `overview_ru`, `overview_en` (string | null) — Episode overview.
  - `short_overview_ru`, `short_overview_en` (string | null) — A one- or two-sentence overview. The English one comes from IMDb.
  - `runtime` (integer | null) — Runtime in minutes.
  - `rating_imdb`, `votes_imdb` (number | null) — IMDb rating and vote count.
  - `rating_kr` (number | null) — Kinorium rating.
  - `still_url` (string | null) — A still from the episode.
- `items with group=season` (array) — A per-season summary.
  - `season` (integer) — Season number.
  - `episodes` (integer) — How many episodes it has.
  - `first_air`, `last_air` (string | null) — Air dates of the first and the last episode.
  - `rating_imdb` (number | null) — The average IMDb rating across the season’s episodes.
  - `votes_imdb` (integer | null) — The sum of IMDb votes across the season’s episodes.
  - `specials` (boolean) — This is the specials season.
- `total`, `limit`, `offset`, `has_more` — Paging, as in [every list](https://kinodata.space/en/docs/lists.md#the-shape-of-a-list).

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | `season` is not a number or is negative; an unknown `group`; a parameter this list doesn’t understand (such as `sort` or `fields`); the response lists the allowed ones. |
| 404 | `not_found` | No title found for this ID. |
| 401 | `unauthorized` | The `X-API-Key` header is missing, or the key is unknown or revoked. |
| 429 | `rate_limited` | The per-second rate limit or the daily quota is used up. |

Every code and what to do about it is on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Examples

### English only

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "season=1" \
  --data-urlencode "limit=1" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1399/episodes"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "season": 1,
      "episode": 1,
      "special": false,
      "imdb_id": "tt1480055",
      "air_date": "2011-04-17",
      "name_en": "Winter Is Coming",
      "name_original": null,
      "overview_en": "Jon Arryn, the Hand of the King, is dead. King Robert Baratheon plans to ask his oldest friend, Eddard Stark, to take Jon's place. Across the sea, Viserys Targaryen plans to wed his sister to a nomadic warlord in exchange for an army.",
      "short_overview_en": null,
      "runtime": 62,
      "rating_imdb": 8.9,
      "votes_imdb": 82456,
      "rating_kr": 8.4,
      "still_url": "https://image.tmdb.org/t/p/original/o4IX9Mm0kpLITVANJMx7inyEUaY.jpg"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 10
}
```

### Season one

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "season=1" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1399/episodes"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "season": 1,
      "episode": 1,
      "special": false,
      "imdb_id": "tt1480055",
      "air_date": "2011-04-17",
      "name_ru": "Зима близко",
      "name_en": "Winter Is Coming",
      "name_original": null,
      "overview_ru": "Отправленный на поиски одичалых отряд воинов сталкивается с куда более пугающим злом, чем племя диких людей. Винтерфелл. Лорд Эддард Старк узнает о поимке дезертира, утверждающего о возвращении белых ходоков, а дети лорда заводят домашних питомцев. Из Королевской гавани приходит известие о смерти советника короля, а также новость о намечающемся визите королевской семьи. Король Роберт Баратеон предлагает Старку не только новую должность, но и объединение семей. Пентос. Ради достижения власти Визерис Таргариен принуждает сестру Дейнерис заключить брачный союз с кхалом Дрого.",
      "overview_en": "Jon Arryn, the Hand of the King, is dead. King Robert Baratheon plans to ask his oldest friend, Eddard Stark, to take Jon's place. Across the sea, Viserys Targaryen plans to wed his sister to a nomadic warlord in exchange for an army.",
      "short_overview_ru": null,
      "short_overview_en": null,
      "runtime": 62,
      "rating_imdb": 8.9,
      "votes_imdb": 82456,
      "rating_kr": 8.4,
      "still_url": "https://image.tmdb.org/t/p/original/o4IX9Mm0kpLITVANJMx7inyEUaY.jpg"
    },
    {
      "season": 1,
      "episode": 2,
      "special": false,
      "imdb_id": "tt1668746",
      "air_date": "2011-04-24",
      "name_ru": "Королевский Тракт",
      "name_en": "The Kingsroad",
      "name_original": null,
      "overview_ru": "Тирион заставляет Джоффри выразить супруге Старк слова сочувствия по поводу случившейся трагедии. Желая подержать Кейтилин, Серсея делится с ней давними переживаниями, в то время как Джон дарит сводной сестре необычный подарок. Сноу готов вступить в ночной дозор, но прежде он пытается разузнать у Старка о своей матери. Несмотря на непрерывную опеку, на Брана совершается покушение, что подтверждает подозрения Сансы о преднамеренности случившегося накануне. Дейнерис знакомится со своими служанками, одна из которых готова поделиться с хозяйкой полезными умениями, а дерзость Арьи навлекает на семью Старков неприятности.",
      "overview_en": "While Bran recovers from his fall, Ned takes only his daughters to Kings Landing. Jon Snow goes with his uncle Benjen to The Wall. Tyrion joins them.",
      "short_overview_ru": null,
      "short_overview_en": null,
      "runtime": 56,
      "rating_imdb": 8.6,
      "votes_imdb": 62610,
      "rating_kr": 8.6,
      "still_url": "https://image.tmdb.org/t/p/original/l0GJx3IR8YasbztTJi5uK0XqkEo.jpg"
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 10
}
```

### Season summary

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "group=season" \
  --data-urlencode "limit=3" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1399/episodes"
```

Response `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "episodes": 10,
      "first_air": "2011-04-17",
      "last_air": "2011-06-19",
      "rating_imdb": 9,
      "season": 1,
      "specials": false,
      "votes_imdb": 643460
    },
    {
      "episodes": 10,
      "first_air": "2012-04-01",
      "last_air": "2012-06-03",
      "rating_imdb": 8.8,
      "season": 2,
      "specials": false,
      "votes_imdb": 531339
    },
    {
      "episodes": 10,
      "first_air": "2013-03-31",
      "last_air": "2013-06-09",
      "rating_imdb": 8.9,
      "season": 3,
      "specials": false,
      "votes_imdb": 636474
    },
    {
      "episodes": 10,
      "first_air": "2014-04-06",
      "last_air": "2014-06-15",
      "rating_imdb": 9.3,
      "season": 4,
      "specials": false,
      "votes_imdb": 697072
    },
    {
      "episodes": 10,
      "first_air": "2015-04-12",
      "last_air": "2015-06-14",
      "rating_imdb": 8.7,
      "season": 5,
      "specials": false,
      "votes_imdb": 607701
    },
    {
      "episodes": 10,
      "first_air": "2016-04-24",
      "last_air": "2016-06-26",
      "rating_imdb": 9,
      "season": 6,
      "specials": false,
      "votes_imdb": 1058322
    },
    {
      "episodes": 7,
      "first_air": "2017-07-16",
      "last_air": "2017-08-27",
      "rating_imdb": 9,
      "season": 7,
      "specials": false,
      "votes_imdb": 572719
    },
    {
      "episodes": 6,
      "first_air": "2019-04-14",
      "last_air": "2019-05-19",
      "rating_imdb": 6.4,
      "season": 8,
      "specials": false,
      "votes_imdb": 1317209
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 8
}
```

### For a movie

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/episodes"
```

Response `200`:

```json
{
  "has_more": false,
  "items": [],
  "limit": 1000,
  "offset": 0,
  "total": 0
}
```