IMDb API: Get movie or show
Gets 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.
Unofficial. Not affiliated with or endorsed by IMDb.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Year optional
year Release or first aired year to distinguish matching names, e.g. 2023.
2023
Whole number.
- Title, required
title Movie or show name, IMDb title link, or title ID, e.g. Oppenheimer or tt15398776.
Oppenheimer
Input as JSON
{ "year": 2023, "title": "Oppenheimer"}Output
{ "cast": [ { "actor": "Cillian Murphy", "character": "J. Robert Oppenheimer" }, { "actor": "Emily Blunt", "character": "Kitty Oppenheimer" }, { "actor": "Matt Damon", "character": "Leslie Groves" } ], "type": "movie", "year": 2023, "title": "Oppenheimer", "budget": { "amount": 100000000, "currency": "USD" }, "genres": [ "Biography", "Drama", "History" ], "runtime": "3 h 0 min", "writers": [ "Christopher Nolan", "Kai Bird", "Martin Sherwin" ], "countries": [ "United States", "United Kingdom" ], "directors": [ "Christopher Nolan" ], "imdb_link": "https://www.imdb.com/title/tt15398776/" , "languages": [ "English", "German", "Italian" ], "metascore": 90, "age_rating": "R", "vote_count": 1101015, "imdb_rating": 8.2, "years_aired": null, "plot_summary": "A dramatization of the life story of J. Robert Oppenheimer, the physicist who had a large hand in the development of the atomic bombs that brought an end to World War II.", "release_date": "2023-07-21", "imdb_title_id": "tt15398776", "awards_summary": "Won 7 Oscars. 370 wins and 378 nominations total.", "runtime_minutes": 180, "worldwide_gross": { "amount": 975811333, "currency": "USD" }, "poster_image_link": "https://m.media-amazon.com/images/M/MV5BN2JkMDc5MGQtZjg3YS00NmFiLWIyZmQtZTJmNTM5MjVmYTQ4XkEyXkFqcGc@._V1_.jpg" }Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"imdb.com/get_movie_or_show","input":{"year":2023,"title":"Oppenheimer"}}' # 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/get_movie_or_show" , "input": { "year": 2023, "title": "Oppenheimer" }})# 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/get_movie_or_show" , "input": { "year": 2023, "title": "Oppenheimer" } }), 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/get_movie_or_show# with {"year":2023,"title":"Oppenheimer"}"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", "required": [ "title" ], "properties": { "year": { "type": "integer", "description": "Release or first aired year to distinguish matching names, e.g. 2023." }, "title": { "type": "string", "description": "Movie or show name, IMDb title link, or title ID, e.g. Oppenheimer or tt15398776." } }}Output schema
{ "type": "object", "required": [ "title", "type", "year", "years_aired", "imdb_rating", "vote_count", "metascore", "age_rating", "runtime", "genres", "plot_summary", "directors", "writers", "cast", "countries", "languages", "release_date", "budget", "worldwide_gross", "awards_summary", "poster_image_link", "imdb_link", "imdb_title_id", "runtime_minutes" ], "properties": { "cast": { "type": "array", "items": { "type": "object", "required": [ "actor", "character" ], "properties": { "actor": { "type": "string" }, "character": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "type": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "budget": { "type": [ "object", "null" ], "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "runtime": { "type": [ "string", "null" ] }, "writers": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "directors": { "type": "array", "items": { "type": "string" } }, "imdb_link": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } }, "metascore": { "type": [ "integer", "null" ] }, "age_rating": { "type": [ "string", "null" ] }, "vote_count": { "type": [ "integer", "null" ] }, "imdb_rating": { "type": [ "number", "null" ], "description": "IMDb user rating out of 10." }, "years_aired": { "type": [ "string", "null" ] }, "plot_summary": { "type": [ "string", "null" ] }, "release_date": { "type": [ "string", "null" ], "format": "date" }, "imdb_title_id": { "type": "string", "x-fous-developer": true }, "awards_summary": { "type": [ "string", "null" ] }, "runtime_minutes": { "type": [ "integer", "null" ], "x-fous-developer": true }, "worldwide_gross": { "type": [ "object", "null" ], "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "additionalProperties": false }, "poster_image_link": { "type": [ "string", "null" ] } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
imdb.com/get_movie_or_show- Returns
- title, type, years, rating, votes, metascore, age rating, runtime, genres, plot, directors, writers, cast, countries, languages, release date, budget, gross, awards, poster, link
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/get_movie_or_show with the inputs above.
Ask your agent
- What's the IMDb rating and vote count for Oppenheimer (2023)?
- Pull up the details for tt0903747 — cast, creators, genres, and how many years it ran.
- Who directed the 2005 version of Pride & Prejudice, and what's its runtime and age rating?
- I need the budget and worldwide gross for Dune: Part Two, plus its metascore and awards summary.
- Get me the plot, poster, and release date for this title: https://www.imdb.com/title/tt7286456/ from IMDb
See more
All IMDb methodsGets 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_guideFinds 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_personLists 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.
imdb.com/list_top_chartsFinds a movie on TMDB by exact title (optionally its release year) or by TMDB movie link, and returns its details, cast, crew, trailers, and the release date, age rating and streaming services for a chosen country.
themoviedb.org/get_movieGets one Netflix movie or series by its exact name or Netflix title URL: title details, publicly shown seasons and episodes, and whether it is available in a given country's catalogue (checked against public JustWatch listings).
netflix.com/get_movie_or_showGets Rotten Tomatoes critic and audience scores and title details for a movie or TV show, optionally for one TV season. Audience rating counts may be unavailable for series.
rottentomatoes.com/get_scoresFinds a TV show on TMDB by exact name or TMDB show link and returns its details, cast, seasons, the last aired and next scheduled episodes, and the streaming services listed for a chosen country.
themoviedb.org/get_tv_showFinds where a movie or show can be watched in a country on JustWatch. Returns streaming, rental and purchase offers with prices, plus ratings and whether it is in cinemas.
justwatch.com/get_where_to_watch