Rotten Tomatoes API: Get scores
Gets 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.
Unofficial. Not affiliated with or endorsed by Rotten Tomatoes.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Year optional
year Release or series start year to distinguish titles. Example: 2021
1984
Whole number.
- Title, required
title Movie or TV show name, or its Rotten Tomatoes link. Example: Barbie
Dune
- Season optional
season TV season number; omit for the whole series. Example: 2
Not set
Whole number 1 or more.
Input as JSON
{ "year": 1984, "title": "Dune"}Output
{ "type": "movie", "year": 1984, "title": "Dune (1984)", "genres": [ "Sci-Fi", "Adventure" ], "runtime": "2h 17m", "director": "David Lynch", "age_rating": "PG-13", "poster_link": "https://resizing.flixster.com/-XZAfHZM39UwaGJIFWKAE8fS0ak=/v3/t/assets/p8382_p_v8_aa.jpg" , "tomatometer": 36, "top_10_cast": [ "Kyle MacLachlan", "Sting", "Francesca Annis" ], "popcornmeter": 65, "verified_hot": false, "us_box_office": null, "critic_reviews": 117, "where_to_watch": [], "certified_fresh": false, "audience_ratings": 12022, "critics_consensus": "This truncated adaptation of Frank Herbert's sci-fi masterwork is too dry to work as grand entertainment, but David Lynch's flair for the surreal gives Dune some spice.", "rotten_tomatoes_link": "https://www.rottentomatoes.com/m/dune_1984" , "us_box_office_currency": null}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"rottentomatoes.com/get_scores","input":{"year":1984,"title":"Dune"}}' # 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": "rottentomatoes.com/get_scores" , "input": { "year": 1984, "title": "Dune" }})# 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": "rottentomatoes.com/get_scores" , "input": { "year": 1984, "title": "Dune" } }), 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 rottentomatoes.com/get_scores# with {"year":1984,"title":"Dune"}"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 series start year to distinguish titles. Example: 2021" }, "title": { "type": "string", "minLength": 1, "description": "Movie or TV show name, or its Rotten Tomatoes link. Example: Barbie" }, "season": { "type": "integer", "minimum": 1, "description": "TV season number; omit for the whole series. Example: 2" } }}Output schema
{ "type": "object", "required": [ "title", "year", "type", "tomatometer", "critic_reviews", "certified_fresh", "popcornmeter", "audience_ratings", "verified_hot", "critics_consensus", "age_rating", "runtime", "genres", "director", "top_10_cast", "where_to_watch", "us_box_office", "us_box_office_currency", "poster_link", "rotten_tomatoes_link" ], "properties": { "type": { "enum": [ "movie", "TV show" ], "type": "string" }, "year": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "genres": { "type": "array", "items": { "type": "string" } }, "runtime": { "type": [ "string", "null" ] }, "director": { "type": [ "string", "null" ] }, "age_rating": { "type": [ "string", "null" ] }, "poster_link": { "type": [ "string", "null" ] }, "tomatometer": { "type": [ "integer", "null" ], "description": "Critics score as a percentage." }, "top_10_cast": { "type": "array", "items": { "type": "string" } }, "popcornmeter": { "type": [ "integer", "null" ], "description": "Audience score as a percentage." }, "verified_hot": { "type": "boolean" }, "us_box_office": { "type": [ "number", "null" ] }, "critic_reviews": { "type": [ "integer", "null" ] }, "where_to_watch": { "type": "array", "items": { "type": "string" } }, "certified_fresh": { "type": "boolean" }, "audience_ratings": { "type": [ "integer", "null" ], "description": "Total audience ratings when the site provides their counts; otherwise null." }, "critics_consensus": { "type": [ "string", "null" ] }, "rotten_tomatoes_link": { "type": "string" }, "us_box_office_currency": { "type": [ "string", "null" ], "description": "USD if US box office is shown." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
rottentomatoes.com/get_scores- Returns
- title, year, type, tomatometer, popcornmeter, review counts, consensus, rating, runtime, genres, director, cast, where to watch, box office, 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 rottentomatoes.com/get_scores with the inputs above.
Ask your agent
- What's the Tomatometer and Popcornmeter for Oppenheimer from 2023?
- Check Rotten Tomatoes scores for season 3 of The Bear
- how well did Dune Part Two do with critics and audiences on rottentomatoes.com
- Get the critic consensus, runtime, and cast for the 1999 movie The Matrix
- Rotten Tomatoes audience score and review counts for Severance season 2, started 2022
See more
All Rotten Tomatoes methodsReads the newest critic or audience reviews for a Rotten Tomatoes movie or TV show. For a whole TV show it combines reviews from its seasons.
rottentomatoes.com/get_reviewsLists Rotten Tomatoes movies in theaters, coming soon, or at home, by genre and site sort order, with scores, release dates, age ratings, posters and links.
rottentomatoes.com/list_moviesGets 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 game, movie or TV show on Metacritic by name and returns critic and user scores with title details.
metacritic.com/get_scoresFinds 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_movieLists 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_reviewedFinds 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_officeGets 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_guide