IMDb API & Scraper
The IMDb API returns movie and TV metadata, ratings and vote counts as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary search endpoint returns titles and people with id, kind, label, image, rank, title type and year, and you can drill into a title (ratings, cast, plot), a person, episodes, charts (the Top 250), reviews, videos, photos and awards. It is built for entertainment apps, recommendation engines and media research that need structured IMDb data without scraping. One ReefAPI key, one shared credit pool, the standard envelope.
IMDb id prefixes, and the one that looks valid but is not
IMDb's own type-ahead mixes three id namespaces into a single result list and only two of them are usable as input here. The third fails with a clear error rather than a mysterious empty response, but it is the most common reason a pipeline breaks on day one. Measured 2026-08-27.
| Field or prefix | What it is | Measured example |
|---|---|---|
| tt + 7 or 8 digits | A movie, series or single episode. The length is not fixed: older titles have 7 digits, newer ones 8. | tt0133093 (The Matrix, 1999), tt31378509 (Dune: Part Three) |
| nm + 7 digits | A person. Takes the person and person_extras actions. | nm0000206 (Keanu Reeves), nm0905154 (Lana Wachowski) |
| in + 7 digits | A franchise or interest page. No action accepts it. | in0000304 ("The Matrix" franchise); title returns INVALID_PARAM |
| title_type on search rows | Lowercase enum on search results. | movie, video, tvSeries, podcastSeries |
| type on the title action | Capitalized on the title card, so the casing differs from title_type. | "Movie" |
| rating / vote_count | Float from 0 to 10, and an integer count. | 8.7 / 2272907 |
| runtime_minutes | Minutes, not seconds. There is no formatted duration string. | 136 |
| popularity_rank vs search rank | The title card's MOVIEmeter position against the type-ahead's own rank. Different indexes. | 154 vs 298 for the same film in the same minute |
Search rows carry kind: "title" even for in… franchise ids, so filtering on `kind` will not save you. Filter on the id prefix instead: accept tt for the title, episodes, reviews, credits, videos, photos, awards and extras actions, accept nm for person and person_extras, and drop everything else.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/imdb/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "the matrix"
}
}{
"ok": true,
"meta": {
"api": "imdb",
"endpoint": "search",
"mode": "live",
"latency_ms": 756,
"record_count": 8,
"bytes": 2381,
"cache_hit": false,
"charged_credits": 1,
"version": "1.0.0"
},
"data": {
"results": [
{
"id": "tt0133093",
"kind": "title",
"label": "The Matrix",
"subtitle": "Keanu Reeves, Laurence Fishburne",
"image": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_.jpg",
"rank": 300,
"title_type": "movie",
"year": 1999
},
{
"id": "in0000304",
"kind": "title",
"label": "The Matrix",
"subtitle": "Franchise",
"image": "https://m.media-amazon.com/images/M/MV5BMWE4Yzk0YTYtNzk2My00NGE1LTg4MmUtM2E3MGQxNjMzNTE5XkEyXkFqcGc@._V1_.jpg",
"rank": 161,
"title_type": null,
"year": null
},
{
"id": "tt0234215",
"kind": "title",
"label": "The Matrix Reloaded",
"subtitle": "Keanu Reeves, Laurence Fishburne",
"image": "https://m.media-amazon.com/images/M/MV5BNjAxYjkxNjktYTU0YS00NjFhLWIyMDEtMzEzMTJjMzRkMzQ1XkEyXkFqcGc@._V1_.jpg",
"rank": 2173,
"title_type": "movie",
"year": 2003
}
]
}
}What the IMDb API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search IMDb for movies, TV shows and people by name. Uses IMDb's own type-ahead, so one query returns titles AND people mixed, each with its IMDb id (tt…/nm…), a subtitle, poster image, popularity rank and (for titles) type and year. Use the returned id with the `title`, `person` or `episodes` actions. | Content platforms call search to search IMDb for movies, TV shows and people by name. | query, kind |
| title | Full IMDb title card for one movie or TV show by its tt… id: IMDb user rating and vote count, year(s), runtime, genres, certificate, plot, countries, languages, directors, writers, top cast with character names, poster and popularity rank. For series it also returns the total episode count. | Research tools call title to get full IMDb title card for one movie or TV show by its tt… id. | imdb_id |
| person | Full IMDb name card for one person by their nm… id: biography, birth/death dates, birthplace, professions, IMDb popularity rank, their best-known titles and a paginated filmography (each credit with the title, year, IMDb rating, the job and — for acting credits — the character played). | Community analysts call person to get full IMDb name card for one person by their nm… id. | imdb_id, role, limit |
| episodes | Episode list for a TV series by its tt… id, with each episode's IMDb rating, vote count, air date, season/episode number and plot. Page one season at a time with `season`; meta lists every available season number and the total episode count. | Media monitors call episodes to get episode list for a TV series by its tt… id, with each episode's IMDb rating, vote count, air…. | imdb_id, season, limit |
| charts | An IMDb chart: the Top 250 movies, Top 250 TV, Bottom 100, or a Most-Popular / Top-Rated meter board. Returns ranked titles with their IMDb chart rating, vote count, year, type and poster. | Content platforms call charts to get an IMDb chart. | chart, limit |
| reviews | User reviews for a movie or TV show by its tt… id — the full IMDb review text plus the reviewer's star rating, headline, date, spoiler flag and helpful up/down votes. Cursor-paginated: pass the returned `next_cursor` back as `cursor` to walk through every review (titles can have thousands). meta.total reports the full review count. | Research tools call reviews to get user reviews for a movie or TV show by its tt… id. | imdb_id, sort, cursor, limit |
| videos | Trailers and video clips for a movie or TV show by its tt… id, each with a playable MP4 URL (multiple qualities), title, type (Trailer/Clip/Featurette), runtime, description and thumbnail. Note: playback URLs are IMDb-signed and time-limited. | Community analysts call videos to get trailers and video clips for a movie or TV show by its tt… id, each with a playable MP4 URL (…. | imdb_id, limit |
| photos | Image gallery for a movie or TV show by its tt… id — posters, stills and event photos with full-resolution URLs, dimensions and captions. Cursor-paginated: pass the returned `next_cursor` back as `cursor`. meta.total reports the gallery size. | Media monitors call photos to get image gallery for a movie or TV show by its tt… id. | imdb_id, cursor, limit |
| awards | Awards and nominations for a movie or TV show by its tt… id — Oscars, Golden Globes, BAFTAs, Emmys and more, each with the event, year, category, win/nomination flag and the people nominated. Cursor-paginated; meta.total reports the full count. | Content platforms call awards to get awards and nominations for a movie or TV show by its tt… id. | imdb_id, cursor, limit |
| extras | Extra IMDb detail for a movie or TV show by its tt… id in one call: trivia, plot keywords, goofs, memorable quotes, alternate titles (AKAs), country release dates, taglines and the parental guide (Sex/Nudity, Violence, Profanity, etc. with severity and example items). Each section is capped by `limit`; section totals are reported. | Research tools call extras to get extra IMDb detail for a movie or TV show by its tt… id in one call. | imdb_id, limit |
| credits | Full cast & crew for a movie or TV show by its tt… id, grouped by department (director, writer, cast, producer, cinematographer, editor, composer, …) — beyond the top-20 cast in `title`. Omit `category` for every department (first N each); pass one `category` to page that department fully with `cursor`. | Community analysts call credits to get full cast & crew for a movie or TV show by its tt… id, grouped by department (director, write…. | imdb_id, category, cursor, limit |
| person_extras | Extra IMDb detail for a person by their nm… id: their photo gallery (full-res URLs + captions), awards and nominations (with the titles they were for), height and alternate names. Complements `person` (bio + filmography). | Media monitors call person_extras to get extra IMDb detail for a person by their nm… id. | imdb_id, cursor, limit |
| whats_new | IMDb's 'what's new' lists: upcoming movies (coming_soon_movies) or TV (coming_soon_tv) with release dates, the weekend box-office top 10 (box_office) with gross earnings, or the currently trending titles (trending). One friendly `list` value picks the board; coming-soon lists are cursor-paginated and region-aware. | Content platforms call whats_new to get iMDb's 'what's new' lists. | list, region, cursor, limit |
Call search from your stack
curl -X POST https://api.reefapi.com/imdb/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"the matrix"}'import requests
r = requests.post(
"https://api.reefapi.com/imdb/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "the matrix"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/imdb/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "the matrix"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.imdb.search with {"query":"the matrix"}.Who uses this API and why
- Streaming and movie apps call title to enrich a film with rating, vote count, cast and plot from an IMDb id.
- Recommendation engines use charts and search to surface top-rated and trending titles.
- Media researchers pull reviews and awards to analyze critical reception across a title's history.
Questions developers ask before integrating
What exactly do the tt, nm and in prefixes mean, and how many digits follow?
tt marks a title (movie, series or episode) and nm marks a person. The digit count is not fixed: The Matrix is tt0133093 with seven digits while Dune: Part Three is tt31378509 with eight, so store them as strings and never parse them as integers, because the leading zeros are load-bearing. Episodes get their own tt ids too: Breaking Bad's pilot is tt0959621. The third prefix, in, marks a franchise or interest page.
Why did an id from the search results fail on the title action?
Because IMDb's type-ahead returns franchise pages alongside real titles. Searching "the matrix" returned in0000304, labelled "The Matrix" with the subtitle "Franchise", sitting second in the list, and passing it to title returned error code INVALID_PARAM with the message "'in0000304' is not a title id (expected tt…)". The row's `kind` said "title", so filter on the prefix of `id` rather than on kind.
Which fields come back null for a film that has not been released yet?
rating and certificate come back null, and vote_count comes back 0 rather than null. A live call on Dune: Part Three (tt31378509) on 2026-08-27 returned rating null, vote_count 0 and certificate null, but release_date "2026-12-18", runtime_minutes 140, five genres and popularity_rank 178 all populated. An unreleased title is fully scheduled and ranked, it just has no user score yet. For movies, episode_count is null too; it is only filled for series.
What unit is runtime in?
Minutes. The Matrix returned runtime_minutes 136 and Dune: Part Three returned 140. There is no seconds field and no pre-formatted "2h 16m" string, so do the formatting on your side.
Why does the title action only give me 20 cast members?
Because it returns IMDb's top billing block, which is what the title page itself shows. The Matrix came back with 20 cast entries and cast_total 41, so the count tells you what you are missing. For the full list, and for every other department, call the credits action with category=cast and page it with the returned cursor. credits also covers director, writer, producer, cinematographer, editor, composer and casting_director.
How do I walk every episode of a series?
Call episodes with the series tt id and a season number. A live call on Breaking Bad (tt0903747, season 1) returned meta.seasons [1, 2, 3, 4, 5] and meta.total_episodes 62, so one call tells you the full shape of the show before you page it. Each episode carries its own tt id, title, season and episode number, air_date, plot, and its own rating and vote_count: the pilot came back as tt0959621 rated 9.1 from 84,900 votes.
Why do two popularity ranks for the same title disagree?
They come from different IMDb indexes. On the same day, The Matrix returned popularity_rank 154 on the title card and rank 298 in the search results. The title card figure is IMDb's MOVIEmeter position, while the search figure is the type-ahead's own ordering signal, which also ranks people and franchises in the same list. Use popularity_rank for anything analytical and treat the search rank purely as result ordering.
Which charts can I pull, and how deep?
Twelve boards: top_250 (the default), top_250_tv, top_250_english, top_250_india, bottom_100, most_popular_movies, most_popular_tv, top_rated_movies, top_rated_tv, lowest_rated_movies, top_rated_english and top_rated_indian. Each entry comes back with rank, tt id, title, year, type, rating, vote_count and poster, and limit accepts 1 to 250, so a single call covers a Top 250 board in full.
What is the IMDb API?
IMDb API is a ReefAPI endpoint group for imdb It returns live JSON through POST requests under /imdb/v1.
Is the IMDb API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. IMDb calls use the same shared credit balance as every other ReefAPI engine.
Do I need an IMDb login or account?
No login to IMDb is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the IMDb data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the IMDb API use?
IMDb actions currently cost 1 credit per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call IMDb from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call imdb actions with the same key, credit pool and JSON envelope used by normal REST requests.