IMDb API
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.
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": 1035.2,
"record_count": 8,
"bytes": 2267,
"cache_hit": false,
"method": "suggestion"
},
"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": 296,
"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": 122,
"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": 1923,
"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 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 a 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, and 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.
Is the IMDb API a IMDb scraper?
It is the managed alternative to a DIY IMDb scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same imdb back as clean JSON.
Why does my IMDb scraper keep getting blocked?
Most IMDb scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.