# Cast and crew

> A title’s actors, dubbing and crew, merged from Kinopoisk, TMDB and Kinorium.

> 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}/cast`

Without parameters the cast comes split into sections by role: directors, actors, writers, producers and so on, 10 people each. To get everyone in one role, narrow the list: `role=actor` gives a flat, pageable list.

`roles` describes the whole cast, not the page: how many people each role has and the role labels. Draw tabs from it; they don’t change while you page.

Dubbing is a role of its own, `voice`: the voice actor, the character they voiced and, in `dubs`, the original actor. People who appear as themselves (in talk shows, ceremonies, documentaries) have the role `self`, and archive footage is `archive`.

## 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

- `role` (csv) — Keep these roles, comma-separated. The list becomes flat and pageable: `role=director,writer` gives directors and writers in one list. `role.not` drops roles and keeps the rest: `role.not=self,archive` is the cast without broadcasts and archive footage. Sections stay; for a flat list, add `group=none`.
  Values: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Example: `role=director,writer`.
- `source` (enum) — Keep the credits this catalog confirmed.
  Values: `kp`, `tmdb`, `kinorium`.
  Example: `source=kp`.
- `group` (enum) — Split the list into sections. `none` gives a flat list. How sections work is in [Lists and pagination](https://kinodata.space/en/docs/lists.md#sections).
  Values: `role`, `none`.
  Default: `role`.
- `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 items to return, a whole number from 1. With sections, per section, up to 50. In a flat list, up to 1000. Above the cap isn’t an error: the API lowers it and shows the value in `limit`.
  Default: 10 per section, 1000 in a flat list. Example: `limit=20`.
- `offset` (integer) — How many items to skip, a whole number from 0. Only in a flat list: with sections it returns `400`.
  Default: 0.

## Response fields

- `roles` (array) — How many people are in the whole cast, by role: `role`, the labels `label_ru` and `label_en`, `count`. The order follows the credits: directors, actors, self, archive footage, writers, producers and so on.
- `items` (array) — Sections by role, each with `role`, labels, `total`, `has_more` and `items`. In a flat list, the credits themselves.
  - `person` (object) — The person. Any of their IDs opens the [person card](https://kinodata.space/en/docs/persons/card.md) and the [filmography](https://kinodata.space/en/docs/persons/filmography.md).
    - `imdb_id`, `kp_id`, `tmdb_id`, `kinorium_id` (string | null) — The person’s catalog IDs.
    - `name_ru`, `name_en` (string | null) — Name in Russian and in English.
    - `name_original` (string | null) — The name in the person’s own language when it is written in neither Latin nor Cyrillic script.
    - `birth_year`, `death_year` (integer | null) — Years of birth and death.
    - `gender` (enum | null) — Gender: `male` or `female`.
    - `photo_url` (string | null) — The portrait, one of `photos_by_source`: the first there is, in the order TMDB, Kinorium, Kinopoisk. As on the [person card](https://kinodata.space/en/docs/persons/card.md).
    - `photos_by_source` (object) — Each source’s photo: `kp`, `tmdb`, `kinorium`. TMDB pictures in the cast are 185 px wide (`/t/p/w185/`); for a larger one, replace that part of the link with `h632` or `original`.
    - `professions` (array) — Professions as the sources list them, values from the `credit_roles` set.
  - `role` (enum) — Role in this title. Labels are in `/enums`, set `credit_roles`.
  - `character_ru`, `character_en` (string | null) — The character, for actors and dubbing. It carries no source notes: “uncredited” is `uncredited`, and “as himself” or “archive footage” is already said by the role `self` or `archive`. A name the source left untranslated comes in `character_en`.
  - `character_original` (string | null) — The character’s name in the original language, when it is neither Russian nor English.
  - `character_photo_url` (string | null) — A still showing this character.
  - `job_ru`, `job_en` (string | null) — The crew job. `job_en` is how TMDB writes it, `job_ru` is the Russian translation: “Director of Photography” → «Оператор-постановщик». Rare jobs have no translation, and `job_ru` is `null`.
  - `dubs` (object | null) — For dubbing, whom the voice actor dubbed: their IDs (`imdb_id`, `kp_id`, `tmdb_id`, `kinorium_id`) and name (`name_ru`, `name_en`).
  - `ord` (integer | null) — Billing order: for actors, the order in the credits; for the crew, within their department. `null` when the place is unknown: the role comes from the person’s filmography, not the title’s credits.
  - `uncredited` (boolean) — `true` means the title’s credits don’t name the person: the source marked the part “uncredited” («в титрах не указан»).
  - `sources` (array) — Which catalogs confirmed the credit: `kp`, `tmdb`, `kinorium`. Two or more mean the person was matched, not guessed. The order is always `kp`, `tmdb`, `kinorium`. A credit only TMDB has is left out when the title’s Kinopoisk or Kinorium cast exists and doesn’t list the person.
- `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` | An unknown role in `role` or `role.not`, an unknown `source` or `group`; a repeated parameter; `offset` together with sections; 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 "role=actor" \
  --data-urlencode "limit=2" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "person": {
        "imdb_id": "nm0000138",
        "kp_id": "37859",
        "tmdb_id": "6193",
        "kinorium_id": "138",
        "name_en": "Leonardo DiCaprio",
        "name_original": null,
        "birth_year": 1974,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_37859.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/138.jpg?20201106112423"
        },
        "professions": [
          "actor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_en": "Dom Cobb",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_138.jpg?1614892697",
      "job_en": null,
      "dubs": null,
      "ord": 0,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    },
    {
      "person": {
        "imdb_id": "nm0330687",
        "kp_id": "9867",
        "tmdb_id": "24045",
        "kinorium_id": "249949",
        "name_en": "Joseph Gordon-Levitt",
        "name_original": null,
        "birth_year": 1981,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_9867.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/249949.jpg?20220127123554"
        },
        "professions": [
          "actor",
          "composer",
          "director",
          "editor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_en": "Arthur",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_249949.jpg?1614363858",
      "job_en": null,
      "dubs": null,
      "ord": 1,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    }
  ],
  "limit": 2,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 87
}
```

### Director

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "role=director" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Response `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "person": {
        "imdb_id": "nm0634240",
        "kp_id": "41477",
        "tmdb_id": "525",
        "kinorium_id": "476400",
        "name_ru": "Кристофер Нолан",
        "name_en": "Christopher Nolan",
        "name_original": null,
        "birth_year": 1970,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_41477.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/476400.jpg?20260829201207"
        },
        "professions": [
          "actor",
          "cinematographer",
          "composer",
          "director",
          "editor",
          "producer",
          "writer",
          "author"
        ]
      },
      "role": "director",
      "character_ru": null,
      "character_en": null,
      "character_original": null,
      "character_photo_url": null,
      "job_ru": null,
      "job_en": null,
      "dubs": null,
      "ord": 0,
      "uncredited": false,
      "sources": [
        "kp",
        "kinorium"
      ]
    }
  ],
  "limit": 1000,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_ru": "Звукорежиссёры",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_ru": "Художники",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_ru": "Режиссёры дубляжа",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_ru": "Дубляж",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 1
}
```

### Actors

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "role=actor" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "person": {
        "imdb_id": "nm0000138",
        "kp_id": "37859",
        "tmdb_id": "6193",
        "kinorium_id": "138",
        "name_ru": "Леонардо ДиКаприо",
        "name_en": "Leonardo DiCaprio",
        "name_original": null,
        "birth_year": 1974,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_37859.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/138.jpg?20201106112423"
        },
        "professions": [
          "actor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_ru": "Кобб",
      "character_en": "Dom Cobb",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_138.jpg?1614892697",
      "job_ru": null,
      "job_en": null,
      "dubs": null,
      "ord": 0,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    },
    {
      "person": {
        "imdb_id": "nm0330687",
        "kp_id": "9867",
        "tmdb_id": "24045",
        "kinorium_id": "249949",
        "name_ru": "Джозеф Гордон-Левитт",
        "name_en": "Joseph Gordon-Levitt",
        "name_original": null,
        "birth_year": 1981,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_9867.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/z2FA8js799xqtfiFjBTicFYdfk.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/249949.jpg?20220127123554"
        },
        "professions": [
          "actor",
          "composer",
          "director",
          "editor",
          "producer",
          "writer"
        ]
      },
      "role": "actor",
      "character_ru": "Артур",
      "character_en": "Arthur",
      "character_original": null,
      "character_photo_url": "https://images.kinorium.com/movie/cast/472809/w300_249949.jpg?1614363858",
      "job_ru": null,
      "job_en": null,
      "dubs": null,
      "ord": 1,
      "uncredited": false,
      "sources": [
        "kp",
        "tmdb",
        "kinorium"
      ]
    }
  ],
  "limit": 2,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_ru": "Звукорежиссёры",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_ru": "Художники",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_ru": "Режиссёры дубляжа",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_ru": "Дубляж",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 87
}
```

### Dubbing

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "role=voice" \
  --data-urlencode "limit=1" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "person": {
        "imdb_id": "nm2511538",
        "kp_id": "1193331",
        "tmdb_id": "932353",
        "kinorium_id": "1570811",
        "name_ru": "Сергей Бурунов",
        "name_en": "Sergey Burunov",
        "name_original": null,
        "birth_year": 1977,
        "death_year": null,
        "gender": "male",
        "photo_url": "https://image.tmdb.org/t/p/w185/c2pbTB0BomzUMZPbTKTZ8wa7byW.jpg",
        "photos_by_source": {
          "kp": "https://st.kp.yandex.net/images/actor_iphone/iphone360_1193331.jpg",
          "tmdb": "https://image.tmdb.org/t/p/w185/c2pbTB0BomzUMZPbTKTZ8wa7byW.jpg",
          "kinorium": "https://images.kinorium.com/persona/300/1570811.jpg?20241003124819"
        },
        "professions": [
          "actor",
          "voice"
        ]
      },
      "role": "voice",
      "character_ru": "Кобб",
      "character_en": "Cobb",
      "character_original": null,
      "character_photo_url": null,
      "job_ru": null,
      "job_en": null,
      "dubs": {
        "kinorium_id": "138",
        "kp_id": "37859",
        "tmdb_id": "6193",
        "imdb_id": "nm0000138",
        "name_ru": "Леонардо ДиКаприо",
        "name_en": "Leonardo DiCaprio"
      },
      "ord": 1,
      "uncredited": false,
      "sources": [
        "kp",
        "kinorium"
      ]
    }
  ],
  "limit": 1,
  "offset": 0,
  "roles": [
    {
      "role": "director",
      "label_ru": "Режиссёры",
      "label_en": "Directors",
      "count": 1
    },
    {
      "role": "actor",
      "label_ru": "Актёры",
      "label_en": "Actors",
      "count": 87
    },
    {
      "role": "writer",
      "label_ru": "Сценаристы",
      "label_en": "Writers",
      "count": 1
    },
    {
      "role": "producer",
      "label_ru": "Продюсеры",
      "label_en": "Producers",
      "count": 10
    },
    {
      "role": "cinematographer",
      "label_ru": "Операторы",
      "label_en": "Cinematographers",
      "count": 1
    },
    {
      "role": "composer",
      "label_ru": "Композиторы",
      "label_en": "Composers",
      "count": 1
    },
    {
      "role": "sound",
      "label_ru": "Звукорежиссёры",
      "label_en": "Sound",
      "count": 6
    },
    {
      "role": "art",
      "label_ru": "Художники",
      "label_en": "Art Department",
      "count": 6
    },
    {
      "role": "editor",
      "label_ru": "Монтажёры",
      "label_en": "Editors",
      "count": 1
    },
    {
      "role": "voice_director",
      "label_ru": "Режиссёры дубляжа",
      "label_en": "Dubbing Directors",
      "count": 1
    },
    {
      "role": "voice",
      "label_ru": "Дубляж",
      "label_en": "Dubbing",
      "count": 16
    }
  ],
  "total": 16
}
```