Rotten Tomatoes API endpoint
Returns Rotten Tomatoes TV season metadata, scorecard data, parent series metadata, and episode rows. Pass exactly one of `path` or `url`.
/rottentomatoes/seasonQuery parameters:
path: Rotten Tomatoes season path, for example /tv/breaking_bad/s01.url: absolute https://www.rottentomatoes.com season URL.Notable response behavior:
data.public_page_derived is true.episodes comes from public TVSeason JSON-LD episode entries.critics_score and audience_score are included only when the public page
exposes scorecard data.| Field | Filled in, of 7 checked | Values in the sample |
|---|---|---|
| episode_number | 7 | 1 to 7, median 4 |
| title | 7 | “Pilot” and 6 other values |
| path | 7 | “/tv/breaking_bad/s01/e01” and 6 other values |
| url | 7 | rottentomatoes.com |
| air_date | 7 | 2008-01-20 to 2008-03-09 |
| description | 7 | median 132 characters |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| path | string | No | Rotten Tomatoes season path | /tv/breaking_bad/s01 | |
| url | string | No | Absolute https://www.rottentomatoes.com season URL | https://www.rottentomatoes.com/tv/breaking_bad/s01 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/rottentomatoes/season" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"title": "Season 1",
"path": "/tv/breaking_bad/s01",
"url": "https://www.rottentomatoes.com/tv/breaking_bad/s01",
"media_type": "TvSeason",
"parent_series": {
"title": "Breaking Bad",
"path": "/tv/breaking_bad"
},
"episode_count": 7,
"critics_score": {
"score_percent": "86%"
},
"audience_score": {
"score_percent": "95%"
},
"public_page_derived": true
}
}Request schema
No body schema
Response schema
#/definitions/rottentomatoes.seasonResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | rottentomatoes.SeasonResponse | No | ||||
| data.audience_score | object | No | Popcornmeter audience score of the season. | |||
| data.audience_score.average_rating | string | No | 8.40 | Average rating as shown on the scorecard, such as `8.40`. | ||
| data.audience_score.banded_rating_count | string | No | 250,000+ Ratings | Approximate number of ratings as shown on the page, such as `250,000+ Ratings`. | ||
| data.audience_score.certified | boolean | No | true | Whether Rotten Tomatoes marks the score as certified. | ||
| data.audience_score.liked_count | integer | No | 314 | Number of ratings that liked the title. | ||
| data.audience_score.not_liked_count | integer | No | 49 | Number of ratings that did not like the title. | ||
| data.audience_score.rating_count | integer | No | 363 | Number of ratings behind the score. | ||
| data.audience_score.review_count | integer | No | 363 | Number of reviews behind the score. | ||
| data.audience_score.reviews_page_url | string | No | https://www.rottentomatoes.com/m/inception/reviews | URL of the Rotten Tomatoes page that lists the reviews behind this score. | ||
| data.audience_score.score | integer | No | 87 | Score as a whole-number percentage. | ||
| data.audience_score.score_percent | string | No | 87% | Score as text with a percent sign, such as `87%`. | ||
| data.audience_score.score_type | string | No | ALL | Audience group the score covers, such as `ALL` or `VERIFIED`. | ||
| data.audience_score.sentiment | string | No | POSITIVE | Overall sentiment of the score, such as `POSITIVE`. | ||
| data.audience_score.title | string | No | Tomatometer | Name of the score, such as `Tomatometer` or `Popcornmeter`. | ||
| data.cast | array | No | People in the cast of the season. | |||
| data.cast[].image_url | string | No | URL of the person's photo. | |||
| data.cast[].name | string | No | Christopher Nolan | Name of the person. | ||
| data.cast[].url | string | No | https://www.rottentomatoes.com/celebrity/christopher_nolan | Rotten Tomatoes page URL of the person. | ||
| data.critics_score | object | No | Tomatometer critics score of the season. | |||
| data.critics_score.average_rating | string | No | 8.40 | Average rating as shown on the scorecard, such as `8.40`. | ||
| data.critics_score.banded_rating_count | string | No | 250,000+ Ratings | Approximate number of ratings as shown on the page, such as `250,000+ Ratings`. | ||
| data.critics_score.certified | boolean | No | true | Whether Rotten Tomatoes marks the score as certified. | ||
| data.critics_score.liked_count | integer | No | 314 | Number of ratings that liked the title. | ||
| data.critics_score.not_liked_count | integer | No | 49 | Number of ratings that did not like the title. | ||
| data.critics_score.rating_count | integer | No | 363 | Number of ratings behind the score. | ||
| data.critics_score.review_count | integer | No | 363 | Number of reviews behind the score. | ||
| data.critics_score.reviews_page_url | string | No | https://www.rottentomatoes.com/m/inception/reviews | URL of the Rotten Tomatoes page that lists the reviews behind this score. | ||
| data.critics_score.score | integer | No | 87 | Score as a whole-number percentage. | ||
| data.critics_score.score_percent | string | No | 87% | Score as text with a percent sign, such as `87%`. | ||
| data.critics_score.score_type | string | No | ALL | Audience group the score covers, such as `ALL` or `VERIFIED`. | ||
| data.critics_score.sentiment | string | No | POSITIVE | Overall sentiment of the score, such as `POSITIVE`. | ||
| data.critics_score.title | string | No | Tomatometer | Name of the score, such as `Tomatometer` or `Popcornmeter`. | ||
| data.description | string | No | Short synopsis of the season. | |||
| data.directors | array | No | Directors of the season. | |||
| data.directors[].image_url | string | No | URL of the person's photo. | |||
| data.directors[].name | string | No | Christopher Nolan | Name of the person. | ||
| data.directors[].url | string | No | https://www.rottentomatoes.com/celebrity/christopher_nolan | Rotten Tomatoes page URL of the person. | ||
| data.ems_id | string | No | 71374db9-1350-30fa-b30a-d3f623bbdfc4 | Rotten Tomatoes' own unique id of the season. | ||
| data.episode_count | integer | No | 7 | Number of episodes in the season. | ||
| data.episodes | array | No | Episodes of the season. | |||
| data.episodes[].air_date | string | No | 2008-01-20 | Date the episode first aired, such as `2008-01-20`. | ||
| data.episodes[].description | string | No | Short synopsis of the episode. | |||
| data.episodes[].episode_number | string | No | 1 | Episode number within the season. | ||
| data.episodes[].path | string | No | /tv/breaking_bad/s01/e01 | Rotten Tomatoes path of the episode page, such as `/tv/breaking_bad/s01/e01`. | ||
| data.episodes[].title | string | No | Pilot | Title of the episode, as Rotten Tomatoes shows it. | ||
| data.episodes[].url | string | No | https://www.rottentomatoes.com/tv/breaking_bad/s01/e01 | Rotten Tomatoes page URL of the episode. | ||
| data.fetched_at | string | No | 2026-06-07T14:46:16Z | Time the data was fetched, in UTC (RFC 3339). | ||
| data.genres | array | No | Crime | Genres of the season. | ||
| data.image_url | string | No | URL of the season image. | |||
| data.lifecycle | string | No | NOT_AIRING | Airing status, such as `NOT_AIRING`. | ||
| data.media_type | string | No | TvSeason | Kind of title, such as `TvSeason`. | ||
| data.parent_series | object | No | Series the season belongs to. | |||
| data.parent_series.ems_id | string | No | 6a74def4-dc62-319e-ae3d-360dcf360244 | Rotten Tomatoes' own unique id of the series. | ||
| data.parent_series.path | string | No | /tv/breaking_bad | Rotten Tomatoes path of the series page, such as `/tv/breaking_bad`. | ||
| data.parent_series.title | string | No | Breaking Bad | Title of the series, as Rotten Tomatoes shows it. | ||
| data.parent_series.url | string | No | https://www.rottentomatoes.com/tv/breaking_bad | Rotten Tomatoes page URL of the series. | ||
| data.path | string | No | /tv/breaking_bad/s01 | Rotten Tomatoes path of the season page, such as `/tv/breaking_bad/s01`. | ||
| data.producers | array | No | Producers of the season. | |||
| data.producers[].image_url | string | No | URL of the person's photo. | |||
| data.producers[].name | string | No | Christopher Nolan | Name of the person. | ||
| data.producers[].url | string | No | https://www.rottentomatoes.com/celebrity/christopher_nolan | Rotten Tomatoes page URL of the person. | ||
| data.public_page_derived | boolean | No | true | Always `true`: the data comes from publicly visible Rotten Tomatoes pages. | ||
| data.release_date | string | No | 2008-01-20 | Date the season premiered, such as `2008-01-20`. | ||
| data.season_number | integer | No | 1 | Number of the season within the series. | ||
| data.source_url | string | No | https://www.rottentomatoes.com/tv/breaking_bad/s01 | URL the data was read from. | ||
| data.title | string | No | Season 1 | Season title, such as `Season 1`. | ||
| data.url | string | No | https://www.rottentomatoes.com/tv/breaking_bad/s01 | Rotten Tomatoes page URL of the season. | ||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/rottentomatoes/season" \
-H "x-api-key: $CRAWLORA_API_KEY"