RottenTomatoes Skill
Fetch movie and TV show ratings, scores, and metadata from RottenTomatoes.
Usage
Search for Movies/TV Shows
typescript
rottentomatoes({
action: 'search',
query: 'The Dark Knight'
})
Returns up to 5 matching results with basic info and scores.
Output:
json
[
{
"title": "The Dark Knight",
"year": 2008,
"type": "movie",
"url": "https://www.rottentomatoes.com/m/the_dark_knight",
"tomatometer": 94,
"audienceScore": 94
}
]
Get Movie Details
typescript
rottentomatoes({
action: 'getMovie',
titleOrUrl: 'The Dark Knight'
})
Or with a direct URL:
typescript
rottentomatoes({
action: 'getMovie',
titleOrUrl: 'https://www.rottentomatoes.com/m/the_dark_knight'
})
Output:
json
{
"title": "The Dark Knight",
"year": 2008,
"type": "movie",
"tomatometer": 94,
"audienceScore": 94,
"criticsConsensus": "Dark, complex, and unforgettable, The Dark Knight succeeds not just as an entertaining comic book film, but as a richly thrilling crime saga.",
"certified": true,
"rating": "PG-13",
"runtime": "2h 32m",
"url": "https://www.rottentomatoes.com/m/the_dark_knight"
}
Get TV Show Details
typescript
rottentomatoes({
action: 'getTVShow',
titleOrUrl: 'Breaking Bad'
})
Output:
json
{
"title": "Breaking Bad",
"year": 2008,
"type": "tv",
"tomatometer": 96,
"audienceScore": 97,
"criticsConsensus": "Breaking Bad is a masterwork of a series...",
"certified": true,
"rating": "TV-MA",
"runtime": null,
"url": "https://www.rottentomatoes.com/tv/breaking_bad"
}
Parameters
action (required)
- •
'search'- Search for movies and TV shows - •
'getMovie'- Get detailed movie information - •
'getTVShow'- Get detailed TV show information
query (required for search)
Search term for movies/TV shows.
titleOrUrl (required for getMovie/getTVShow)
Either:
- •Movie/TV show title (will search first)
- •Direct RottenTomatoes URL
Output Fields
| Field | Type | Description |
|---|---|---|
title | string | Full title of the movie/show |
year | number | null | Release year |
type | 'movie' | 'tv' | Content type |
tomatometer | number | null | Critics score (0-100) |
audienceScore | number | null | Audience score (0-100) |
criticsConsensus | string | null | Summary of critical reception |
certified | boolean | Certified Fresh status |
rating | string | null | MPAA/TV rating (PG-13, R, TV-MA, etc.) |
runtime | string | null | Duration |
url | string | RottenTomatoes page URL |
Features
- •✅ Rate Limiting: Exponential backoff, max 1 request per 2 seconds
- •✅ Caching: 24-hour cache to reduce requests
- •✅ Anti-Detection: Rotating user agents, random delays
- •✅ Proxy Support: Use
PROXY_URLenvironment variable - •✅ 429 Handling: Automatic retry with backoff
Environment Variables
- •
PROXY_URL(optional) - HTTP/HTTPS proxy for requests
Examples
Quick movie lookup
typescript
const result = await rottentomatoes({
action: 'getMovie',
titleOrUrl: 'Oppenheimer'
});
console.log(`${result.title}: ${result.tomatometer}% 🍅`);
Search and pick
typescript
const results = await rottentomatoes({
action: 'search',
query: 'Dune'
});
// Get details for the first result
const details = await rottentomatoes({
action: 'getMovie',
titleOrUrl: results[0].url
});
Error Handling
All functions return an error object if something goes wrong:
json
{
"error": "Movie not found: Invalid Title"
}
Notes
- •Scores are parsed from the page and may change as RT updates their UI
- •Search results are limited to 5 items
- •Certified Fresh status indicates high critic scores
- •TV shows may not have runtime information
- •Cache is in-memory and resets when skill restarts
Rate Limiting
To avoid being blocked:
- •Minimum 2 seconds between requests
- •Random 1-3 second jitter added
- •Exponential backoff on 429 errors (starts at 1s, max 60s)
- •24-hour cache to minimize redundant requests
Respect RottenTomatoes' servers! Don't hammer the API.