Box Office Mojo API: List top grossing movies
Lists the highest-grossing movies of a calendar year, ranked by domestic or worldwide gross, with release dates and distributors.
Unofficial. Not affiliated with or endorsed by Box Office Mojo.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Year optional
year Calendar year to rank, such as 2025. Defaults to the current year.
2025
Whole number from 1900 to 2100.
- Scope optional
scope Box office market to rank, such as worldwide.
domestic
One of
domestic,worldwide. Defaultdomestic.- Max Results optional
max_results Maximum number of ranked movies to return, such as 25.
5
Whole number from 1 to 200. Default
50.
Input as JSON
{ "year": 2025, "scope": "domestic", "max_results": 5}Output
{ "movies": [ { "link": "https://www.boxofficemojo.com/release/rl746096129/" , "rank": 1, "gross": 423949195, "title": "A Minecraft Movie", "currency": "USD", "distributor": "Warner Bros.", "release_date": "2025-04-04", "domestic_gross": null, "international_gross": null, "widest_release_theaters": 4289 }, { "link": "https://www.boxofficemojo.com/release/rl3104735233/" , "rank": 2, "gross": 423778855, "title": "Lilo & Stitch", "currency": "USD", "distributor": "Walt Disney Studios Motion Pictures", "release_date": "2025-05-23", "domestic_gross": null, "international_gross": null, "widest_release_theaters": 4410 }, { "link": "https://www.boxofficemojo.com/release/rl1543340801/" , "rank": 3, "gross": 354184465, "title": "Superman", "currency": "USD", "distributor": "Warner Bros.", "release_date": "2025-07-11", "domestic_gross": null, "international_gross": null, "widest_release_theaters": 4275 } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"boxofficemojo.com/list_top_grossing_movies","input":{"year":2025,"scope":"domestic","max_results":5}}' # 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": "boxofficemojo.com/list_top_grossing_movies" , "input": { "year": 2025, "scope": "domestic", "max_results": 5 }})# 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": "boxofficemojo.com/list_top_grossing_movies" , "input": { "year": 2025, "scope": "domestic", "max_results": 5 } }), 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 boxofficemojo.com/list_top_grossing_movies# with {"year":2025,"scope":"domestic","max_results":5}"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": [], "properties": { "year": { "type": "integer", "maximum": 2100, "minimum": 1900, "description": "Calendar year to rank, such as 2025. Defaults to the current year." }, "scope": { "enum": [ "domestic", "worldwide" ], "type": "string", "default": "domestic", "description": "Box office market to rank, such as worldwide." }, "max_results": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1, "description": "Maximum number of ranked movies to return, such as 25." } }, "additionalProperties": false}Output schema
{ "type": "object", "required": [ "movies" ], "properties": { "movies": { "type": "array", "items": { "type": "object", "required": [ "rank", "title", "gross", "currency", "domestic_gross", "international_gross", "widest_release_theaters", "release_date", "distributor", "link" ], "properties": { "link": { "type": "string" }, "rank": { "type": "integer" }, "gross": { "type": [ "number", "null" ] }, "title": { "type": "string" }, "currency": { "type": "string" }, "distributor": { "type": [ "string", "null" ] }, "release_date": { "type": [ "string", "null" ], "format": "date" }, "domestic_gross": { "type": [ "number", "null" ] }, "international_gross": { "type": [ "number", "null" ] }, "widest_release_theaters": { "type": [ "integer", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
boxofficemojo.com/list_top_grossing_movies- Returns
- rank, title, gross, domestic and international gross, release date, distributor, 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 boxofficemojo.com/list_top_grossing_movies with the inputs above.
Ask your agent
- What were the top 25 highest-grossing movies at the domestic box office in 2019?
- Show me the biggest worldwide box office hits of 2008 ranked by total gross
- Which films earned the most money in US theaters in 2014, with distributors and release dates?
- I need a ranked list of the top 50 worldwide earners from 2022 on boxofficemojo.com
- List the top 10 domestic grossing films from 1995 along with their international earnings
See more
All Box Office Mojo methodsReturns the domestic US and Canada daily box office rankings for a date, or the latest reported day when no date is given.
boxofficemojo.com/get_daily_box_officeFinds a movie on Box Office Mojo by title, with an optional year, and returns its box office totals, release details, theater counts and markets.
boxofficemojo.com/get_movie_box_officeReturns ranked box office grosses for a weekend in a market. Defaults to the latest reported US and Canada weekend; international markets use their own weekend calendar.
boxofficemojo.com/get_weekend_box_officeLists 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_filmsLooks up a film on The Numbers by title (and optional release year) and returns its budget, box office, physical disc sales and release details.
the-numbers.com/get_movie_financialsLists 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_chartsLists Fandango movies now playing or coming soon in U.S. theaters, in Fandango's order, with release dates, age ratings, runtimes and Rotten Tomatoes scores when shown.
fandango.com/list_now_playingLists the highest-Metascore games, movies or TV shows on Metacritic for a release year or all time. You can filter by genre, and by platform for games.
metacritic.com/list_best_reviewed