IMDb API: List top charts
Lists titles in an IMDb movie or TV chart (Top 250 movies, Top 250 TV shows, most popular movies or TV shows) with ratings, votes, runtime, age rating and weekly rank movement for popularity charts. Popular charts contain up to 100 titles.
Unofficial. Not affiliated with or endorsed by IMDb.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Chart optional
chart Chart to list, for example top_250_movies.
top_250_movies
One of
top_250_movies,top_250_tv_shows,most_popular_movies,most_popular_tv_shows. Defaulttop_250_movies.- Max Results optional
max_results Maximum number of titles, for example 50. Popular charts have at most 100 titles.
50
Whole number from 1 to 250. Default
50.
Input as JSON
{ "chart": "top_250_movies", "max_results": 50}Output
{ "titles": [ { "rank": 1, "year": 1994, "title": "The Shawshank Redemption", "votes": 3244669, "runtime": "2 h 22 min", "title_id": "tt0111161", "imdb_link": "https://www.imdb.com/title/tt0111161/" , "age_rating": "R", "imdb_rating": 9.3, "runtime_minutes": 142, "rank_change_since_last_week": null }, { "rank": 2, "year": 1972, "title": "The Godfather", "votes": 2259997, "runtime": "2 h 55 min", "title_id": "tt0068646", "imdb_link": "https://www.imdb.com/title/tt0068646/" , "age_rating": "R", "imdb_rating": 9.2, "runtime_minutes": 175, "rank_change_since_last_week": null }, { "rank": 3, "year": 2008, "title": "The Dark Knight", "votes": 3232530, "runtime": "2 h 32 min", "title_id": "tt0468569", "imdb_link": "https://www.imdb.com/title/tt0468569/" , "age_rating": "PG-13", "imdb_rating": 9.1, "runtime_minutes": 152, "rank_change_since_last_week": null } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"imdb.com/list_top_charts","input":{"chart":"top_250_movies","max_results":50}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "imdb.com/list_top_charts" , "input": { "chart": "top_250_movies", "max_results": 50 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "imdb.com/list_top_charts" , "input": { "chart": "top_250_movies", "max_results": 50 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run imdb.com/list_top_charts# with {"chart":"top_250_movies","max_results":50}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "properties": { "chart": { "enum": [ "top_250_movies", "top_250_tv_shows", "most_popular_movies", "most_popular_tv_shows" ], "type": "string", "default": "top_250_movies", "description": "Chart to list, for example top_250_movies." }, "max_results": { "type": "integer", "default": 50, "maximum": 250, "minimum": 1, "description": "Maximum number of titles, for example 50. Popular charts have at most 100 titles." } }}Output schema
{ "type": "object", "required": [ "titles" ], "properties": { "titles": { "type": "array", "items": { "type": "object", "required": [ "rank", "title", "year", "imdb_rating", "votes", "runtime", "age_rating", "imdb_link", "rank_change_since_last_week", "title_id", "runtime_minutes" ], "properties": { "rank": { "type": "integer", "description": "Position in the chosen chart." }, "year": { "type": [ "integer", "null" ], "description": "First release year, if available." }, "title": { "type": "string", "description": "Movie or show title." }, "votes": { "type": [ "integer", "null" ], "description": "Number of IMDb rating votes, if available." }, "runtime": { "type": [ "string", "null" ], "description": "Runtime, such as 2 h 22 min, if available." }, "title_id": { "type": "string", "description": "IMDb title identifier." }, "imdb_link": { "type": "string", "description": "IMDb page for this title." }, "age_rating": { "type": [ "string", "null" ], "description": "Content rating, such as R or TV-MA, if available." }, "imdb_rating": { "type": [ "number", "null" ], "description": "IMDb audience rating out of 10, if available." }, "runtime_minutes": { "type": [ "integer", "null" ], "description": "Runtime in minutes, if available." }, "rank_change_since_last_week": { "type": [ "integer", "null" ], "description": "Weekly popularity chart rank change: positive means moved up, negative means moved down, zero means unchanged; null when unavailable or not a popularity chart." } } }, "description": "Titles in chart order." } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
imdb.com/list_top_charts- Returns
- rank, title, year, IMDb rating, votes, runtime, age rating, IMDb link, weekly rank change, title ID, runtime minutes
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method imdb.com/list_top_charts with the inputs above.
Ask your agent
- Show me the top 20 highest-rated movies of all time on IMDb with their ratings and vote counts
- Which TV shows are trending most right now? Give me the top 50 along with how much each moved up or down in rank this week
- I need the full list of 250 best-rated TV series, including year, runtime and age rating for each
- What are the 10 most popular movies on IMDb this week?
- Pull the first 100 entries from the all-time greatest films ranking with their title IDs and runtime in minutes
See more
All IMDb methodsGets a movie or TV show's IMDb details from its name, IMDb title link or title ID; a year picks between titles with the same name. Unavailable details are null.
imdb.com/get_movie_or_showFinds a film person on IMDb by name, IMDb person link or person ID and returns their biography, awards summary, known-for titles and filmography (without self-appearances, archive footage and thanks).
imdb.com/get_personGets age certifications and non-spoiler Parents Guide summaries (severity votes and example descriptions for five categories) for a movie or show by title, IMDb link or title ID. A year selects a specific release.
imdb.com/get_parents_guideLists ranked Roblox experiences from a current Charts list. Each game includes players online, approval percentage, creator, icon and game link.
roblox.com/list_top_gamesLists titles on JustWatch's daily streaming chart for a country, optionally limited to one streaming service.
justwatch.com/list_streaming_chartsLists Letterboxd films in popularity order for a week, month, year or all time, optionally filtered by genre and decade. Ratings and posters may be unavailable for some films.
letterboxd.com/list_popular_filmsLists Apple Podcasts chart entries in rank order for a country and category, as top shows or top episodes.
podcasts.apple.com/list_top_podcastsLists ranked Android apps or games from the Google Play top free, top paid or top grossing chart for a country and category.
play.google.com/list_top_charts