How do I get the cast list of a series?

Call GET /3/tv/{series_id}/credits and sort the cast array by order. Season credits cover one season, and episode credits add guest_stars. amodb does not offer aggregate TV credits.

How do I find the director of a movie?

Read the crew array and pick the entry whose job is Director. A film can have more than one director, so collect every match instead of stopping at the first.

What does the order field mean?

Order is the billing position of a cast member, with 0 for the first billed. Sort cast by order to show the lead roles first. Crew entries have no order.

Where do guest stars come from?

Only the episode credits endpoint returns a guest_stars array, next to crew. Its cast array is empty. Season and series credits do not list guest stars separately.

Credits API: TMDB v3 compatible cast and crew endpoints

Get movie credits

GET /3/movie/{movie_id}/credits returns two arrays for one movie: cast for people who appear on screen and crew for people who worked behind the camera. Every entry holds the person id, so you can open the full record on the people page. The same data is available inside the movie reply with append_to_response=credits.

The example reads Inception, prints the director and lists the five first billed actors.

curl JavaScript Python PHP Go

curl -sSf "https://api.amodb.dev/3/movie/27205/credits?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const credits = await res.json();
const director = credits.crew.find((c) => c.job === 'Director');
console.log('Director:', director?.name);
for (const c of [...credits.cast].sort((a, b) => a.order - b.order).slice(0, 5)) {
  console.log(c.order, c.name, 'as', c.character);
}

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/27205/credits",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
credits = r.json()
director = next((c for c in credits["crew"] if c["job"] == "Director"), None)
print("Director:", director and director["name"])
for c in sorted(credits["cast"], key=lambda c: c["order"])[:5]:
    print(c["order"], c["name"], "as", c["character"])

<?php
$url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$credits = json_decode($body, true);
usort($credits['cast'], fn ($a, $b) => $a['order'] <=> $b['order']);
foreach (array_slice($credits['cast'], 0, 5) as $c) {
    echo $c['order'], ' ', $c['name'], ' as ', $c['character'], PHP_EOL;
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Credits struct {
	Cast []struct {
		Order     int    `json:"order"`
		Name      string `json:"name"`
		Character string `json:"character"`
	} `json:"cast"`
	Crew []struct {
		Name string `json:"name"`
		Job  string `json:"job"`
	} `json:"crew"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/27205/credits?language=en-US", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var c Credits
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	for _, m := range c.Crew {
		if m.Job == "Director" {
			fmt.Println("Director:", m.Name)
		}
	}
	for i, a := range c.Cast {
		if i == 5 {
			break
		}
		fmt.Println(a.Order, a.Name, "as", a.Character)
	}
}

Parameters

Parameter	In	Required	Description
`movie_id`	path	yes	Numeric movie id, for example `27205`.
`api_key`	query	one of two	Your key. Use this or the `Authorization: Bearer` header.
`language`	query	no	TMDB tag such as `en-US` or `fr-FR`. Tags outside the 14 base languages fall back to `en`.

Response fields

Field	Applies to	Notes
`id`	top level	Id of the movie, series, season or episode the credits belong to.
`cast`, `crew`	top level	Arrays of entries. Episode credits add `guest_stars`.
`id`	each entry	Person id. Open it with people.
`name`, `original_name`	each entry	The person's name.
`known_for_department`	each entry	The person's main job overall, not the job on this title.
`gender`, `popularity`, `adult`	each entry	Same meaning as on the person record.
`profile_path`	each entry	Image path or null. Append to `https://img.amodb.dev/t/p/{size}`.
`credit_id`	each entry	String that identifies this one credit.
`character`	cast, guest stars	Role name, empty for some entries.
`order`	cast, guest stars	Billing position, `0` is first.
`department`	crew	Group such as `Directing`, `Writing`, `Production`, `Camera`, `Editing`, `Sound`, `Art`, `Visual Effects`, `Lighting`, `Costume & Make-Up` or `Crew`.
`job`	crew	Specific job, for example `Director`, `Screenplay` or `Editor`.

Example response

GET /3/movie/27205/credits?language=en-US. The reply has 52 cast and 735 crew entries today, so both arrays are cut to two here:

JSON

{
  "id": 27205,
  "cast": [
    {
      "adult": false,
      "gender": 2,
      "id": 6193,
      "known_for_department": "Acting",
      "name": "Leonardo DiCaprio",
      "original_name": "Leonardo DiCaprio",
      "popularity": 9.3213,
      "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
      "character": "Dom Cobb",
      "credit_id": "52fe4534c3a368484e04de03",
      "order": 0
    },
    {
      "adult": false,
      "gender": 2,
      "id": 24045,
      "known_for_department": "Acting",
      "name": "Joseph Gordon-Levitt",
      "original_name": "Joseph Gordon-Levitt",
      "popularity": 5.6202,
      "profile_path": "/z2FA8js799xqtfiFjBTicFYdfk.jpg",
      "character": "Arthur",
      "credit_id": "52fe4534c3a368484e04de0b",
      "order": 1
    }
  ],
  "crew": [
    {
      "adult": false,
      "gender": 2,
      "id": 1025090,
      "known_for_department": "Crew",
      "name": "Jim Wilkey",
      "original_name": "Jim Wilkey",
      "popularity": 0.9114,
      "profile_path": "/peEdS7ZYHwEeMJAwInJj732AeYs.jpg",
      "credit_id": "6634553bad59b501286dab5f",
      "department": "Crew",
      "job": "Stunt Driver"
    },
    {
      "adult": false,
      "gender": 2,
      "id": 1741194,
      "known_for_department": "Sound",
      "name": "James Thatcher",
      "original_name": "James Thatcher",
      "popularity": 0.6215,
      "profile_path": null,
      "credit_id": "5bcdece8925141613e0216d3",
      "department": "Sound",
      "job": "Musician"
    }
  ]
}

TV, season and episode credits

All paths below share the base https://api.amodb.dev/3 and take language.

Method and path	Returns
`GET /tv/{series_id}/credits`	Cast and crew of the series, one entry per person and role.
`GET /tv/{series_id}/season/{season_number}/credits`	Cast and crew of one season.
`GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits`	`crew` and `guest_stars` for one episode. `cast` is an empty array.

The same data is available with append_to_response=credits on the series, season and episode paths. The entry shape matches the movie credits above. Episode guest stars carry character and order, and crew entries carry department and job.

GET /3/tv/1399/season/1/episode/1/credits?language=en-US, with the arrays cut to two entries:

JSON

{
  "id": 63056,
  "cast": [],
  "crew": [
    {
      "department": "Writing",
      "job": "Writer",
      "credit_id": "5256c8a019c2956ff6046e2b",
      "adult": false,
      "gender": 2,
      "id": 9813,
      "known_for_department": "Writing",
      "name": "David Benioff",
      "original_name": "David Benioff",
      "popularity": 2.0354,
      "profile_path": "/xvNN5huL0X8yJ7h3IZfGG4O2zBD.jpg"
    },
    {
      "department": "Editing",
      "job": "Editor",
      "credit_id": "54eef2ab925141795f005d4f",
      "adult": false,
      "gender": 2,
      "id": 18077,
      "known_for_department": "Editing",
      "name": "Oral Norrie Ottey",
      "original_name": "Oral Norrie Ottey",
      "popularity": 0,
      "profile_path": null
    }
  ],
  "guest_stars": [
    {
      "character": "Benjen Stark",
      "credit_id": "5256c8b919c2956ff604836a",
      "order": 61,
      "adult": false,
      "gender": 2,
      "id": 119783,
      "known_for_department": "Acting",
      "name": "Joseph Mawle",
      "original_name": "Joseph Mawle",
      "popularity": 1.4645,
      "profile_path": "/1Ocb9v3h54beGVoJMm4w50UQhLf.jpg"
    },
    {
      "character": "Rickon Stark",
      "credit_id": "566a83bcc3a3683f56003604",
      "order": 80,
      "adult": false,
      "gender": 2,
      "id": 1050248,
      "known_for_department": "Acting",
      "name": "Art Parkinson",
      "original_name": "Art Parkinson",
      "popularity": 1.2594,
      "profile_path": "/ejAKOJME1DsvHECLWdQ7dEtXyyc.jpg"
    }
  ]
}

amodb does not offer aggregate TV credits or a lookup by credit_id. For a series cast list, read /tv/{series_id}/credits and sort cast by order.

Reading cast and crew in an app

Task	How
Show the director	Pick the `crew` entries with `job` equal to `Director`. A film can have several.
Show the lead cast	Sort `cast` by `order` and take the first 10.
Group the crew	Group by `department`. A person with two jobs appears twice, so merge on the person `id`.
Show a series cast	Read the series credits and sort `cast` by `order`.
List all departments and jobs	Read the lookup list described on genres and lookup lists.

Errors

HTTP	status_code	When
401	7	The key is missing or wrong.
402	36	The plan period has ended.
404	34	The movie, series, season or episode does not exist, or the path is not offered.
405	37	You called a write method.
429	25	Over your requests per minute. Wait for the `Retry-After` seconds.

Details are on errors and rate limits.

Practical notes

Credits are cached for 6 hours, like details. A new cast member can take that long to appear.
A large production can list hundreds of crew entries. Slice the arrays before you render them.
profile_path is null for people without a photo. Use w185 for list rows and h632 for detail views.
Movie and TV records are in movies and TV series. Season and episode records are on seasons and episodes.