# Actor API > The actor API is the people family of TMDB v3 at api.amodb.dev/3. Fetch a person with GET /3/person/{person_id}, add combined_credits for the full filmography and images for profile photos. A popular list, name search and IMDb id lookup use the same key and JSON shape. ## 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 | Endpoint | Returns | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `GET /3/person/{person_id}` | `name`, `biography`, `birthday`, `deathday`, `place_of_birth`, `known_for_department`, `profile_path`, `imdb_id` | | `GET /3/person/{person_id}/movie_credits` | Movie roles in `cast` and jobs in `crew` | | `GET /3/person/{person_id}/tv_credits` | The same for series | | `GET /3/person/{person_id}/combined_credits` | Movies and TV in one list, tagged by `media_type` | | `GET /3/person/{person_id}/images` | A `profiles` array of photos | | `GET /3/person/popular` | Paged list of popular people | | `GET /3/search/person` | People matching a `query` | ## Start in 3 steps 1. Pick a plan on [pricing](https://amodb.dev/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. ```bash curl -s "https://api.amodb.dev/3/person/31?language=en-US&append_to_response=combined_credits" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```python 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. ```json { "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. | Field | Rows | Meaning | | ---------------------------------- | --------------------- | ------------------------------------- | | `media_type` | combined credits | `movie` or `tv` | | `title` or `name` | movie rows or TV rows | Display title | | `release_date` or `first_air_date` | movie rows or TV rows | Sort key, may be empty | | `character` | cast | Role name | | `job`, `department` | crew | For example `Director` in `Directing` | | `credit_id` | both | Id of the credit row | 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](https://amodb.dev/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](https://amodb.dev/images-api/). ## 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](https://amodb.dev/find-by-external-id/). ## How it compares | Capability | Scrape pages yourself | Free-tier metadata API | amodb | | ------------------- | ---------------------------- | ---------------------- | -------------------------------------- | | Filmography | Crawl one page per credit | Check their docs | `combined_credits` in a single call | | Cast and crew split | Parse section headings | Check their docs | `cast` and `crew` arrays | | Photos | Download and resize yourself | Check their docs | Fixed sizes on `img.amodb.dev`, no key | | Name search | Drive a site search form | Check their docs | `GET /3/search/person` | | Id mapping | Match by name | Check their docs | `/3/find` with `imdb_id` | | Languages | One locale per site | Check their docs | 14 languages via `language` | ## 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](https://amodb.dev/pricing/). ## Questions and answers ### How do I get all movies and shows an actor appeared in? Call GET /3/person/{person_id}/combined_credits, or add append_to_response=combined_credits to the person call. The cast array holds roles from movies and TV, each tagged with media_type, so one request covers the whole filmography. ### Can I find an actor by name? Yes. GET /3/search/person with the query parameter returns matching people with ids, names and profile paths. Search results are cached for 10 minutes, so repeated lookups of a popular name are cheap. ### Where do actor photos come from and do they need a key? Each person has a profile_path. Join it to https://img.amodb.dev/t/p/{size} with a size such as w185 or h632. Image requests need no key, and the edge keeps images for 30 days. ### How do I match an actor to an IMDb name id? Call GET /3/find/{external_id}?external_source=imdb_id and read person_results. The person record also returns imdb_id, so you can store both ids side by side and look up in either direction. ### Are biographies available in other languages? Yes, through the language parameter, for the 14 served languages. The name follows your language when a translation exists. When a biography has no translation, the person record returns the English text. ## Related pages - [Person details API](https://amodb.dev/people/): Person details API with the same paths and JSON as TMDB v3. Get an actor or crew member by id, with biography, filmography, external ids and the popular list. - [Credits API](https://amodb.dev/credits/): Credits API with the same paths and JSON as TMDB v3. Get cast and crew for movies, series, seasons and episodes, with order, department and job fields. - [Images API and the TMDB image path](https://amodb.dev/images-api/): Build a TMDB image path: https://img.amodb.dev/t/p/{size}/{file}. List posters, backdrops and logos per title, then load them in 10 sizes with no key. - [Search API](https://amodb.dev/search/): Search API with the same paths and JSON as TMDB v3. Find movies, TV shows, people, collections, companies and keywords by text, with year filters and paging. - [Find by external id](https://amodb.dev/find-by-external-id/): Look up a movie, series or person by IMDb, TVDB, Wikidata or Kinopoisk id with the TMDB find endpoint, and read external ids and Wikidata facts for a title. - [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes. Updated: 2026-10-18. Source: https://amodb.dev/actor-api/