Skip to content
scrapeatlas.Dashboard

Film & TV

IMDb API

Retrieve IMDb movie and TV titles, people, search results, user reviews and charts.

5 endpointsx-api-key

Look up any movie, series or episode with ratings, cast, crew and box office, read actor and director profiles with known-for titles, search titles and people, page through user reviews and list the IMDb Top 250 and most popular charts.

API availability: Available

Base URL · local workerhttp://localhost:3058Public API: https://api.scrapeatlas.com.
Authenticationx-api-keyCustomer key from your account. See Authentication.

Endpoints

GET/v1/imdb/title

Get an IMDb title

Retrieve a movie, series or episode by IMDb ID or URL: title, type, year, runtime, genres, rating and vote count, Metascore, plot, poster, release date, certificate, directors, writers, creators, top cast, countries, languages, popularity rank and box office.

Reference
GET/v1/imdb/person

Get an IMDb person

Retrieve an actor, director or other person by IMDb name ID or URL: bio, birth and death details, professions, alternate names, popularity rank, known-for titles and filmography credit counts.

Reference
GET/v1/imdb/search

Search IMDb

Search IMDb titles and people by keyword, with type, year, rating and vote count for titles and professions and a known-for title for people. Pass nextCursor to read the next page.

Reference
GET/v1/imdb/reviews

List IMDb user reviews

List user reviews for a title with reviewer, rating, headline, text, spoiler flag, date and helpful votes, sorted by helpfulness, date, rating or votes. Pass nextCursor to read the next page.

Reference
GET/v1/imdb/chart

Get an IMDb chart

List an IMDb chart such as the Top 250 movies or TV shows or the most popular movies or TV shows, with rank, year, rating, votes, runtime, certificate, genres and poster.

Reference

Quick start

Create an API key on your account page, then call the public API. Values below are placeholders.

Terminal
curl "https://api.scrapeatlas.com/v1/imdb/title?id=tt0111161" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Title: an IMDb title ID (tt followed by 7 to 10 digits) or an imdb.com title URL. Person: an IMDb name ID (nm followed by 7 to 10 digits) or an imdb.com name URL. Query: 1 to 100 characters. Cursor: up to 1,024 characters.
  • Page sizes: search 1 to 50 (default 20), reviews 1 to 25 (default 25), charts 1 to 250 (default 50). Titles return at most 15 cast members and 10 people per principal credit group; people return at most 4 known-for titles and 10 alternate names.
  • Each read has a 15-second deadline and each operation a 30-second deadline, including the queue wait. Decoded responses are capped at 2 MiB.
  • At most two upstream requests per operation: one read and one shared retry after a network failure or HTTP 5xx.
  • At most six active requests and twelve queued requests, with a queue wait of at most 10 seconds.
  • Fixed origin api.graphql.imdb.com. No login, cookies, image downloads or result storage. The service API key is never forwarded.
Error codes
13
HTTPfailure.codeMeaning
200partialUsable data with named field-error, invalid-item, record-limit or total warnings.
400invalid_requestMissing, duplicate, malformed or unsupported parameters, or a cursor IMDb rejected.
401unauthorizedMissing or invalid worker API key.
404not_foundThe requested IMDb title or person was not found.
422unsupported_pageThe IMDb response structure or identity could not be mapped.
502upstream_challengedIMDb challenged retrieval.
502upstream_rate_limitedIMDb rate-limited retrieval.
502upstream_errorSource retrieval did not complete.
502response_too_largeDecoded source bytes exceeded the request limit.
502unsafe_redirectIMDb answered with a redirect, which is never followed.
502request_limitThe upstream request budget was exhausted.
503busyWorker request or queue capacity was exceeded.
504timeoutThe operation deadline expired.