MDBList APImdblist.com ↗
Search and list movies from MDBList with ratings from IMDb, Trakt, TMDb, Letterboxd, Rotten Tomatoes, Metacritic, and more via a single API endpoint.
What is the MDBList API?
The MDBList Movies API exposes one endpoint — list_movies — that returns up to 48 movies per page with aggregate scores from seven rating sources including IMDb, Trakt, TMDb, Letterboxd, Rotten Tomatoes, Metacritic, and RogerEbert. Each movie object includes title, release year, description, poster URL, slug, and a combined score alongside individual platform ratings, making it practical for discovery tools, recommendation engines, and data pipelines that need multi-source film ratings in a single response.
curl -X GET 'https://api.parse.bot/scraper/8dc5d446-e78d-42ed-9389-75953af462f6/list_movies?page=0&sort=score&sort_order=asc' \ -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 mdblist-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: MDBList SDK — search and browse movies with multi-source ratings."""
from parse_apis.mdblist_com_api import MDBList, Sort, SortOrder, InvalidSort
client = MDBList()
# List top-rated movies by MDBList aggregate score
for movie in client.movies.search(sort=Sort.SCORE, sort_order=SortOrder.ASC, limit=5):
print(movie.title, f"score={movie.score}")
# Search for movies by title, sorted by IMDb rating
movie = client.movies.search(sort=Sort.IMDB_RATING, title="godfather", limit=1).first()
if movie:
print(movie.title, movie.year, movie.slug)
if movie.ratings:
for source, rating in movie.ratings.items():
print(f" {source}: {rating.rating} ({rating.votes} votes)")
# Handle invalid sort parameter gracefully
try:
client.movies.search(sort=Sort.RELEASED, title="matrix", limit=3).first()
except InvalidSort as exc:
print(f"Invalid sort: {exc}")
print("exercised: movies.search (by score / by imdb_rating / by released)")
Search and list movies with configurable sort order and optional title filter. Returns paginated results including aggregate scores and ratings from IMDb, Trakt, TMDb, Letterboxd, Rotten Tomatoes, Metacritic, and RogerEbert. Results are auto-iterated across pages (48 movies per page). The sort_order 'asc' returns highest values first for rating-based sorts.
| Param | Type | Description |
|---|---|---|
| page | integer | Zero-based page number for pagination. Each page returns up to 48 movies. |
| sort | string | Sort field for ordering results. |
| title | string | Filter movies by title or IMDb ID. Partial matches supported. |
| sort_order | string | Sort direction. 'asc' returns highest values first for rating-based sorts, 'desc' returns lowest first. |
{
"type": "object",
"fields": {
"page": "integer - current page number",
"count": "integer - number of movies returned on this page",
"total": "string - total number of matching movies (may include '+' suffix for large sets)",
"movies": "array of movie objects with title, year, score, ratings, description, poster_url, and slug"
},
"sample": {
"page": 0,
"count": 48,
"total": "10001",
"movies": [
{
"slug": "c0ro-12-angry-men",
"year": 1957,
"score": 93,
"title": "12 Angry Men (1957)",
"ratings": {
"imdb": {
"votes": 988871,
"rating": 9
},
"tmdb": {
"votes": 10074,
"rating": 85
},
"trakt": {
"votes": 13254,
"rating": 88
},
"tomato": {
"votes": 63,
"rating": 100
},
"popcorn": {
"votes": 6766,
"rating": 97
},
"letterboxd": {
"votes": 1557142,
"rating": 4.6
},
"metacritic": {
"votes": 18,
"rating": 97
},
"rogerebert": {
"votes": null,
"rating": 4
}
},
"poster_url": "https://image.tmdb.org/t/p/w200/zhG3vKWyDRaZYoaww1UVAi29T9h.jpg",
"description": "The defense and the prosecution have rested and the jury is filing into the jury room..."
}
]
}
}About the MDBList API
What the API Returns
The list_movies endpoint returns a paginated list of movies sourced from MDBList. Each response includes a page integer, a count of movies on that page, a total field indicating how many movies match your query (which may carry a + suffix for large result sets), and a movies array. Each movie object carries title, year, score, individual ratings from IMDb, Trakt, TMDb, Letterboxd, Rotten Tomatoes, Metacritic, and RogerEbert, a description, a poster_url, and a slug.
Filtering and Sorting
The title parameter accepts partial strings or an IMDb ID, letting you narrow results to a specific film or a set of title matches. The sort parameter controls which field drives ordering — typical sort fields include rating-based values — and sort_order sets the direction: asc returns highest values first for rating-based sorts, while desc returns lowest first. Pagination is handled via a zero-based page integer; each page contains up to 48 movies.
Practical Notes
The total field is a string rather than an integer because MDBList may return a + suffix (e.g. "1000+") when the true count exceeds a threshold. Consumers should parse this defensively. The ratings array consolidates scores that would otherwise require separate API calls to IMDb, Trakt, TMDb, and other platforms, reducing the overhead of building multi-source comparison views.
The MDBList API is a managed, monitored endpoint for mdblist.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when mdblist.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 mdblist.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?+
- Build a movie recommendation feed sorted by a specific rating source such as Letterboxd or Metacritic score
- Populate a film discovery UI with poster images, descriptions, and release years from a single paginated call
- Compare cross-platform consensus scores (IMDb vs. Rotten Tomatoes vs. RogerEbert) for a given title using the
titlefilter - Generate ranked lists of top-rated or lowest-rated films by toggling
sort_orderbetweenascanddesc - Look up a specific film by IMDb ID using the
titleparameter to retrieve its aggregate MDBList score alongside platform ratings - Build a data pipeline that collects multi-source movie ratings at scale using the
pageparameter to iterate across the full catalog
| 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 MDBList have an official developer API?+
What does the `ratings` field in each movie object include?+
ratings field contains individual scores from IMDb, Trakt, TMDb, Letterboxd, Rotten Tomatoes, Metacritic, and RogerEbert alongside a combined score. These are returned in a single response rather than requiring separate lookups per platform.Does the `total` field always return an exact count?+
+ suffix (for example, "1000+"), meaning the precise total is not exposed. Consumers should treat total as a string and handle the + case before parsing it as a number.Does the API cover TV shows or only movies?+
list_movies endpoint. TV show data is not included. You can fork this API on Parse and revise it to add a TV show endpoint targeting MDBList's show listings.Can I retrieve the full cast, crew, or genre tags for each movie?+
list_movies endpoint returns title, year, score, ratings, description, poster URL, and slug per movie. Cast, crew, and genre data are not part of the response shape. You can fork this API on Parse and revise it to add an endpoint that retrieves detailed movie metadata.