IMDb APIimdb.com ↗
Fetch IMDb movie details, ratings, cast, crew, budget, and box office data via two structured endpoints. Covers any title by IMDb ID.
What is the IMDb API?
The IMDb API exposes 2 endpoints that return structured data for any title on IMDb, including ratings, cast, plot, genres, budget, and runtime. The get_movie_details endpoint delivers over 10 response fields in a single call — title, year, rating with vote count, genres, plot summary, primary image, budget with currency, and a configurable cast list. For productions with large ensembles, get_full_cast supports cursor-based pagination across the complete cast list.
curl -X GET 'https://api.parse.bot/scraper/fe7b024f-ea0d-489a-b060-6f5bda26ccb7/get_movie_details?title_id=tt0816692&cast_limit=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace imdb-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: IMDb Movie Details API — bounded, re-runnable; every call capped."""
from parse_apis.imdb_movie_details_api import IMDb, TitleNotFound
client = IMDb()
# Fetch a movie by its IMDb title ID and inspect its details.
movie = client.movies.get(title_id="tt0816692")
print(movie.title, movie.year, movie.runtime)
print("Rating:", movie.rating.value, "from", movie.rating.vote_count, "votes")
print("Genres:", movie.genres)
# Access nested typed fields — budget and worldwide gross as Money objects.
if movie.budget:
print(f"Budget: {movie.budget.amount} {movie.budget.currency}")
if movie.worldwide_gross:
print(f"Worldwide gross: {movie.worldwide_gross.amount} {movie.worldwide_gross.currency}")
# Drill into directors and writers (typed CrewMember / Writer resources).
for d in movie.directors:
print("Director:", d.name, d.id)
for w in movie.writers:
print("Writer:", w.name, w.category)
# Paginate full cast via the sub-resource — limit caps total items fetched.
for member in movie.cast_members.list(limit=5):
print(member.name, member.id, member.characters)
# Typed error handling — catch TitleNotFound for an invalid title ID.
try:
client.movies.get(title_id="tt9999999")
except TitleNotFound as exc:
print(f"Title not found: {exc.title_id}")
print("Exercised: movies.get / movie.rating / movie.budget / movie.directors / movie.writers / movie.cast_members.list")
Get comprehensive movie details including title, plot overview, IMDb rating, genres, cast (with character names), directors, writers, budget, box office, keywords, and more. The cast returned is capped by cast_limit; use get_full_cast for the complete list with pagination.
| Param | Type | Description |
|---|---|---|
| title_idrequired | string | IMDb title ID (e.g., tt0816692). The 'tt' prefix is optional. |
| cast_limit | integer | Maximum number of cast members to return (max 50). |
{
"type": "object",
"fields": {
"cast": "array of {name, id, characters}",
"plot": "string, plot summary",
"type": "string, content type (e.g. Movie, TV Series)",
"year": "integer, release year",
"image": "string, URL of primary image",
"title": "string, movie title",
"budget": "object with amount (integer) and currency (string), or null",
"genres": "array of genre strings",
"rating": "object with value (float) and vote_count (integer)",
"runtime": "string, human-readable runtime",
"writers": "array of {name, id, category}",
"end_year": "integer or null, end year for series",
"keywords": "array of keyword strings",
"taglines": "array of tagline strings",
"title_id": "string, IMDb title ID",
"countries": "array of country name strings",
"directors": "array of {name, id}",
"languages": "array of language name strings",
"total_cast": "integer, total number of cast members",
"release_date": "string, formatted release date (YYYY-MM-DD)",
"content_rating": "string, content rating (e.g. PG-13)",
"original_title": "string, original language title",
"runtime_seconds": "integer, runtime in seconds",
"worldwide_gross": "object with amount (integer) and currency (string), or null"
}
}About the IMDb API
Movie Details in One Request
The get_movie_details endpoint accepts an IMDb title ID (e.g., tt0816692) via the title_id parameter — the tt prefix is optional. The response includes the title, year, type (Movie, TV Series, etc.), plot summary, genres array, image URL, and a rating object containing both the score (value) and vote_count. Financial fields include budget (an object with amount and currency, or null if unavailable) and box office data. Cast is returned as an array of objects with name, id, and characters, capped via the optional cast_limit parameter (max 50).
Paginating Through Full Cast
When a production has more cast members than the 50-member cap in get_movie_details, the get_full_cast endpoint provides cursor-based pagination. Pass the same title_id and optionally set limit (up to 50 per page). The response includes total (total cast count for the title), has_next_page, and end_cursor — pass the cursor back as after on the next request to step through the full list. Each cast record carries name, id, and characters.
Response Shape and Data Scope
Both endpoints use the IMDb title ID as the primary key, so any title searchable on IMDb is addressable. The type field distinguishes movies from TV series and other formats. Budget and box office fields reflect reported figures and may be null for titles where this data is not publicly listed on IMDb. Runtime is returned as a human-readable string rather than raw minutes.
The IMDb API is a managed, monitored endpoint for imdb.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when imdb.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official imdb.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Populating a film database with structured metadata including genres, year, runtime, and plot summaries.
- Building a ratings tracker that surfaces IMDb
rating.valueandvote_countfor a watchlist of title IDs. - Aggregating budget and box office figures across a catalog of movies for financial analysis.
- Rendering full cast pages for any title using paginated results from
get_full_cast. - Filtering a content library by
typeto separate movies from TV series using the same endpoint. - Enriching a recommendation engine with genre arrays and keyword data from
get_movie_details. - Displaying cast cards with character names by extracting the
charactersfield from cast objects.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does IMDb have an official developer API?+
What does the `rating` field in `get_movie_details` include?+
rating object contains two fields: value (a float, the weighted average IMDb score) and vote_count (an integer representing the number of user ratings). Neither critic scores nor Metascore values are part of this response.Is TV episode-level data available through these endpoints?+
How reliable is the `budget` field — will it always be populated?+
budget field returns null when budget information is not listed on the IMDb title page. This is common for independent films, older titles, and international productions. Box office data has similar coverage gaps. Plan for null-checking in any pipeline that depends on these financial fields.Can I search for a title by name instead of by IMDb ID?+
get_movie_details and get_full_cast require a known IMDb title ID (title_id). There is no search-by-name endpoint in this API. You can fork it on Parse and revise it to add a title search endpoint that resolves names to IMDb IDs.