Rotten Tomatoes APIeditorial.rottentomatoes.com ↗
Access Rotten Tomatoes movie and TV metadata, Tomatometer scores, critic reviews, celebrity filmographies, and editorial news via 7 structured endpoints.
What is the Rotten Tomatoes API?
The Rotten Tomatoes editorial API covers 7 endpoints that return movie and TV metadata, paginated critic reviews, celebrity filmographies, trending browse listings, and editorial news articles. The get_movie_details endpoint returns structured JSON-LD data including cast, director, genre, content rating, aggregate Tomatometer score, and a UUID-format EMS ID required to fetch critic reviews through get_reviews.
curl -X GET 'https://api.parse.bot/scraper/0ca817bf-4b53-4671-acfc-052c237cd967/search?query=batman' \ -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 editorial-rottentomatoes-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.
from parse_apis.rotten_tomatoes_api import RottenTomatoes, BrowseStatus
rt = RottenTomatoes(api_key="YOUR_API_KEY")
# Search for movies
for result in rt.searchresults.search(query="dune"):
print(result.title, result.score, result.url)
# Get movie details and browse reviews
movie = rt.movies.get(slug="dune_part_two")
print(movie.slug, movie.ems_id)
for review in movie.reviews.list(page_count=5):
print(review.score_sentiment, review.original_score, review.review_quote)
# Browse trending movies in theaters
for item in rt.browseitems.list(status=BrowseStatus.MOVIES_IN_THEATERS):
print(item.title, item.score)
# Get latest news articles
for article in rt.articles.list(per_page=5):
print(article.id, article.date, article.link)
# Get person filmography
person = rt.people.get(person_slug="timothee_chalamet")
print(person.person_slug, person.metadata)
Full-text search across movies, TV shows, and people on Rotten Tomatoes. Returns a single page of server-rendered results with title, URL, thumbnail, Tomatometer score (where available), and year. Results are not paginated; up to ~20 results returned.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword or phrase |
{
"type": "object",
"fields": {
"results": "array of search result objects each with title, url, image, year, and score"
},
"sample": {
"data": {
"results": [
{
"url": "https://www.rottentomatoes.com/m/the_batman",
"year": null,
"image": "https://resizing.flixster.com/sbvU-SvlSRsyWqxAxsnaE1qFdLc=/fit-in/80x126/v2/...",
"score": null,
"title": "The Batman"
},
{
"url": "https://www.rottentomatoes.com/tv/batman_caped_crusader",
"year": "2024",
"image": "https://resizing.flixster.com/...",
"score": "94%",
"title": "Batman: Caped Crusader"
}
]
},
"status": "success"
}
}About the Rotten Tomatoes API
Movie and TV Show Data
The get_movie_details and get_tv_show_details endpoints each accept a URL slug (e.g. dune_part_two or breaking_bad) and return JSON-LD metadata fields including name, genre, actor, director, aggregateRating, contentRating, dateCreated, and image. The TV endpoint additionally exposes numberOfSeasons and containsSeason. Both endpoints return an emsId field — a UUID used as the required input to get_reviews.
Critic Reviews and Pagination
get_reviews accepts an ems_id, an optional page_count to control batch size, and an optional after cursor for cursor-based pagination. Each review object includes reviewId, scoreSentiment, originalScore, reviewQuote, createDate, and a nested critic object with displayName. The pageInfo object in the response exposes hasNextPage, hasPreviousPage, and endCursor for stepping through large review sets.
Search, Browse, and People
The search endpoint accepts a free-text query and returns up to ~20 results, each with title, url, image, year, and score. browse_movies returns trending title tiles filtered by an optional status category, each with a relative url, poster image, and score percentage string. get_person_details resolves a person_slug to a JSON-LD Person record with birthDate, birthPlace, description, and an itemListElement filmography list, alongside a parsed filmography array of credits with rating, title, url, role, and year.
Editorial News
get_news_articles returns WordPress post objects from the Rotten Tomatoes editorial site ordered by publication date. Each object includes id, date, slug, link, title.rendered, excerpt.rendered, author, and jetpack_featured_media_url. Pagination is page-based via page and per_page parameters (max 100 per page).
The Rotten Tomatoes API is a managed, monitored endpoint for editorial.rottentomatoes.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when editorial.rottentomatoes.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 editorial.rottentomatoes.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 comparison tool using
aggregateRatingandcontentRatingfields fromget_movie_details - Aggregate critic sentiment by pulling
scoreSentimentandoriginalScorefrom paginatedget_reviewsresponses - Power a celebrity lookup feature using
birthDate,birthPlace, and filmography fromget_person_details - Track trending titles by monitoring
browse_moviesoutput across differentstatuscategories - Surface Rotten Tomatoes editorial coverage in a film news feed using
get_news_articleswithjetpack_featured_media_url - Enrich a content database with genre, cast, and season data from
get_tv_show_details - Implement a site-wide search widget using the
title,year, andscorefields returned bysearch
| 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 Rotten Tomatoes have an official developer API?+
How does cursor-based pagination work in get_reviews?+
get_reviews response includes a pageInfo object with hasNextPage (boolean) and endCursor (string). Pass the endCursor value as the after parameter in your next request to fetch the following page. If hasNextPage is false, you have reached the last page of reviews for that EMS ID.Does get_search return audience scores or only Tomatometer scores?+
search endpoint returns the score field, which reflects the Tomatometer percentage where available. Audience scores (Popcornmeter) are not included in search results. You can fork this API on Parse and revise it to add an endpoint that retrieves audience score data from individual title pages.Are full critic review texts returned, or just excerpts?+
reviews array in get_reviews returns a reviewQuote field, which is the excerpt published on Rotten Tomatoes rather than the full original review text. Full review bodies hosted on external critic publications are not included. You can fork this API on Parse and revise it to follow the linked publication URL and retrieve extended review content.Does browse_movies support pagination or filtering by genre?+
browse_movies returns all items rendered on a single browse page for the given status category. Genre-based filtering is not a supported parameter. You can fork this API on Parse and revise it to add genre filter parameters if Rotten Tomatoes exposes genre browse pages via distinct URL paths.