Actor API

Look up an actor and their filmography

GET /3/person/{person_id} returns a biography, birth data and a profile image path for one person. Add append_to_response=combined_credits and the same reply holds every movie and TV credit too. Ids are the numeric person ids TMDB uses, for example 31 for Tom Hanks.

You get a person record, a cast and crew filmography, profile photos, and lists for discovery. Actors, directors and writers all live in the same endpoints and differ by known_for_department.

What data you get

Start in 3 steps

1. Pick a plan on pricing. All plans return the same data and differ only in requests per minute.
2. Generate a key in your account dashboard.
3. Send GET /3/person/31 with Authorization: Bearer YOUR_API_KEY, or use api_key in the query string.

Example request

This call fetches Tom Hanks with his combined credits. The Python sample keeps movie roles that have a release date, sorts them newest first and prints five, plus the photo URL.

curl -s "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \
  -H "Authorization: Bearer $AMODB_KEY"

import os
import requests

BASE = "https://api.amodb.dev/3"
HEADERS = {"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}

r = requests.get(
    f"{BASE}/person/31",
    params={"language": "en-US", "append_to_response": "combined_credits"},
    headers=HEADERS,
    timeout=10,
)
r.raise_for_status()
person = r.json()

movies = [
    c for c in person["combined_credits"]["cast"]
    if c["media_type"] == "movie" and c.get("release_date")
]
movies.sort(key=lambda c: c["release_date"], reverse=True)

print(person["name"], person["birthday"], person["known_for_department"])
if person.get("profile_path"):
    print("Photo:", "https://img.amodb.dev/t/p/w342" + person["profile_path"])
for c in movies[:5]:
    print(c["release_date"][:4], c["title"], "as", c.get("character") or "n/a")

Trimmed response for language=en-US. combined_credits is cut to 2 cast rows and 1 crew row, and the biography is shortened.

{
  "adult": false,
  "also_known_as": [
    "Thomas Jeffrey Hanks"
  ],
  "biography": "Thomas Jeffrey Hanks (born July 9, 1956) is an American actor and filmmaker. Known for...",
  "birthday": "1956-07-09",
  "deathday": null,
  "gender": 2,
  "homepage": null,
  "id": 31,
  "imdb_id": "nm0000158",
  "known_for_department": "Acting",
  "name": "Tom Hanks",
  "place_of_birth": "Concord, California, USA",
  "popularity": 12.98,
  "profile_path": "/oFvZoKI6lvU03n4YoNGAll9rkas.jpg",
  "combined_credits": {
    "cast": [
      {
        "adult": false,
        "backdrop_path": "/owUcU7WcM42uPXIVJHglDQceY5R.jpg",
        "genre_ids": [
          12,
          16,
          35
        ],
        "id": 1084244,
        "original_language": "en",
        "original_title": "Toy Story 5",
        "overview": "",
        "popularity": 158.5027,
        "poster_path": "/sfQtVlIHljToOwYjhe21KPGzZWK.jpg",
        "release_date": "2026-06-17",
        "title": "Toy Story 5",
        "video": false,
        "vote_average": 8.285,
        "vote_count": 2649,
        "media_type": "movie",
        "credit_id": "65edd5772790bf01634423c9",
        "character": "Woody (voice)",
        "order": 0
      },
      {
        "adult": false,
        "backdrop_path": "/1dvOCqKgBcXvfqzVPmAAM5Rv4PP.jpg",
        "genre_ids": [
          16,
          35,
          10751
        ],
        "id": 863,
        "original_language": "en",
        "original_title": "Toy Story 2",
        "overview": "",
        "popularity": 49.6885,
        "poster_path": "/4rbcp3ng8n1MKHjpeqW0L7Fnpzz.jpg",
        "release_date": "1999-10-30",
        "title": "Toy Story 2",
        "video": false,
        "vote_average": 7.6,
        "vote_count": 15484,
        "media_type": "movie",
        "credit_id": "5ac0152ec3a368443f034084",
        "character": "Woody (voice)",
        "order": 0
      }
    ],
    "crew": [
      {
        "adult": false,
        "backdrop_path": "/23GjGDQdMHW5C2UYwSV00fE3FNi.jpg",
        "first_air_date": "2001-09-09",
        "genre_ids": [
          18,
          10768
        ],
        "id": 4613,
        "name": "Band of Brothers",
        "origin_country": [],
        "original_language": "en",
        "original_name": "Band of Brothers",
        "overview": "",
        "popularity": 63.5427,
        "poster_path": "/pGzV187ogXzgJrvPRy2YPi29ofH.jpg",
        "vote_average": 8.608,
        "vote_count": 4424,
        "media_type": "tv",
        "credit_id": "5257765d760ee36aaa522862",
        "department": "Production",
        "job": "Executive Producer"
      }
    ]
  }
}

Build a filmography

A person can appear in cast and in crew of the same title, for example an actor who also directs. Treat the two arrays as separate lists and merge them in your own view. Movie and TV rows use different field names, so read the right one.

Sort by date, put rows without a date last, and de-duplicate on the pair id and media_type. TV cast rows carry episode_count, but amodb returns 0 there, so do not use it to count episodes. amodb does not offer GET /3/credit/{credit_id} or aggregate_credits. The details of cast and crew fields are on credits.

Profile photos

profile_path joins to the image host: https://img.amodb.dev/t/p/{size}{profile_path}. Use w185 for list thumbnails, h632 for a profile page and original for downloads. Images need no key and are cached for 30 days.

For more than one photo call GET /3/person/{person_id}/images. The profiles array has file_path, width, height, aspect_ratio and vote_average, so you can pick the best rated portrait. Size tables and srcset are on images.

Popular people, search and id lookup

• GET /3/person/popular?page=1 returns a paged list. Pages run from 1 to 500, and the list is cached for 30 minutes.
• GET /3/search/person?query=tom+hanks matches by name. Cached for 10 minutes.
• GET /3/find/{external_id}?external_source=imdb_id maps an IMDb name id to a person. Read person_results in the reply. See find by external id.

How it compares

Pricing

Pay up front for 1, 3, 6, 12 or 24 months. Longer periods take 0, 10, 20, 30 or 40 percent off, and plans never renew on their own. The three plans allow 20, 40 and 120 requests per minute, and each one returns every people endpoint. A cast grid for a movie costs one credits request, because names and profile paths come with it, and a person page costs one request with credits appended. Choose the rate that matches your page views. No free tier. Start on pricing.