The rating everyone quotes, as a field
The IMDb API returns movie and TV metadata, ratings and vote counts as clean JSON.
13 active endpoints. Every call is 1 credit.
- POST/imdb/v1/search
- POST/imdb/v1/title
- POST/imdb/v1/person
- POST/imdb/v1/episodes
- POST/imdb/v1/charts
- POST/imdb/v1/reviews
- POST/imdb/v1/videos
- +6 more
What IMDb endpoints does ReefAPI ship?
13 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
IMDb API
3 of 13 endpoints, ready to run
One title by its IMDb id: rating and vote count, year, release date, runtime, certificate, genres, plot and whether it is a series.
{ "ok": true, "meta": { "api": "imdb", "endpoint": "title", "mode": "live", "latency_ms": 1942.6, "record_count": 1, "cache_hit": false }, "data": { "title": { "id": "tt0133093", "title": "The Matrix", "original_title": "The Matrix", "type": "Movie", "is_series": false, "year": 1999, "end_year": null, "release_date": "1999-03-31", "runtime_minutes": 136, "rating": 8.7, "vote_count": 2273565, "certificate": "R", "genres": [ "Action", "Sci-Fi" ], "plot": "A computer hacker discovers that his life is nothing more than an elaborate simulation run by an evil AI.", "image": "https://m.media-amazon.com/images/M/MV5BN2NmN2VhMTQtMDNiOS00NDlhLTliMjgtODE2ZTY0ODQyNDRhXkEyXkFqcGc@._V1_.jpg", "popularity_rank": 154, "countries": [ "United States" ], "languages": [ "English" ], "directors": [ { "id": "nm0905154", "name": "Lana Wachowski" }, { "id": "nm0905152", "name": "Lilly Wachowski" } ], "writers": [ { "id": "nm0905152", "name": "Lilly Wachowski" }, { "id": "nm0905154", "name": "Lana Wachowski" } ], "cast": [ { "id": "nm0000206", "name": "Keanu Reeves", "characters": [ "Neo" ] }, { "id": "nm0000401", "name": "Laurence Fishburne", "characters": [ "Morpheus" ] }, { "id": "nm0005251", "name": "Carrie-Anne Moss", "characters": [ "Trinity" ] } ], "cast_total": 41 } } }
How the IMDb API works
IMDb is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 184 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Turning a title someone typed into a stable id
Everything downstream — streaming availability, a rating comparison, a recommendation — keys on the IMDb id. The user gives you a name.
{"query": "the matrix"}Returns candidates with the id, the year and a subtitle naming the leads, which is what disambiguates a remake from the original.
{"imdb_id": "tt0133093"}Then the full record. The IMDb id is the identifier the rest of the media catalogue accepts, so this call is the join key for everything else.
Two calls and you hold the identifier that streaming availability, the film databases and the review sites all recognise.
curl -X POST https://api.reefapi.com/imdb/v1/title \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"imdb_id":"tt0133093"}'{
"ok": true,
"data": { … },
"meta": {
"api": "imdb",
"endpoint": "title",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Whose judgement this is, and what a search row leaves out
Measured on a well-known film, a search and the charts.
Every other media engine here accepts it — the film databases, streaming availability, the review sites. That is what makes this engine the entry point rather than one of several equivalent sources: it produces the identifier the others agree on.
A rating is meaningless without the number of votes behind it. Both are returned as numbers rather than as display strings, so an 8.7 from two million votes is distinguishable from an 8.7 from four hundred — which is the difference between a consensus and an accident.
Age certification comes back with the title, which is the field a content-filtering or family-facing product needs first and which is frequently missing from film datasets entirely.
A search row carries the id, the label, the year, the type and a subtitle naming the leads — enough to pick the right title, not enough to build a card. Take the id and call title; the rating and plot are not on the search row.
The rating here is IMDb's audience. Letterboxd's cinephile average and a critic aggregate will disagree with it, sometimes sharply, and the disagreement is frequently the interesting part. If you are building a comparison, treat this as one input rather than as the score.
What people build with IMDb
The jobs this data is most often used for.
endpoints
credit per call
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.
What IMDb data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 184 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/imdb/v1/title \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"imdb_id":"tt0133093"}'import requests
r = requests.post(
"https://api.reefapi.com/imdb/v1/title",
headers={"x-api-key": REEF_KEY},
json={
"imdb_id": "tt0133093"
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up IMDb.
Get a free key →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, 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.
25 Media, Film & Knowledge APIs on the same key
One key, one credit pool, one response envelope. If you are pulling IMDb, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 183 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-30.