# TV seasons and episodes API > Read one season with every episode at GET /3/tv/{series_id}/season/{season_number}, or a single episode one level deeper. The JSON matches TMDB v3 with air_date, episode_number, runtime and still_path. Each episode carries crew and guest_stars, season 0 holds specials, and append_to_response adds credits, images and videos. ## Endpoint `GET /3/tv/{series_id}/season/{season_number}` ```bash curl "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Response: ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to team up with a former student and create a top of the line crystal meth in a used RV, to provide for his family once he is gone.", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7029219c29533d00dd2c1", "adult": false, "gender": 2, "id": 2483, "known_for_department": "Camera", "name": "约翰·托尔", "original_name": "约翰·托尔", "popularity": 1.1957, "profile_path": "/cfL9A6tC7L5Ps5fq1o3WpVKGMb1.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee313280006e8", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" }, { "character": "Jock", "credit_id": "52542275760ee313280006b4", "order": 500, "adult": false, "gender": 2, "id": 1216132, "known_for_department": "Acting", "name": "Aaron Hill", "original_name": "Aaron Hill", "popularity": 1.6521, "profile_path": "/rNp31SeoVqSQU6OZWxZUhGwAgyq.jpg" }, { "character": "Dr. Belknap", "credit_id": "52725cb1760ee3044d0b9984", "order": 502, "adult": false, "gender": 2, "id": 161591, "known_for_department": "Acting", "name": "Gregory Chase", "original_name": "Gregory Chase", "popularity": 0.5435, "profile_path": "/gNdodev00CROpXuAh5EFmkWTVOo.jpg" } ] }, { "air_date": "2008-01-27", "episode_number": 2, "episode_type": "standard", "id": 62086, "name": "Cat's in the Bag...", "overview": "Walt and Jesse attempt to tie up loose ends. The desperate situation gets more complicated with the flip of a coin. Walt's wife, Skyler, becomes suspicious of Walt's strange behavior.", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/AbMoecO0ZZio0LcgeLxlzdyGs6X.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.jpg" } ], "guest_stars": [ { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" }, { "character": "Ob-Gyn", "credit_id": "63012c9c5f4b73008267ba53", "order": 682, "adult": false, "gender": 0, "id": 1448105, "known_for_department": "Acting", "name": "Shane Marinson", "original_name": "Shane Marinson", "popularity": 0, "profile_path": null }, { "character": "Ben", "credit_id": "63012d2111c066007cbc37b1", "order": 683, "adult": false, "gender": 0, "id": 3670897, "known_for_department": "Acting", "name": "Jason Byrd", "original_name": "Jason Byrd", "popularity": 0, "profile_path": null } ] }, { "air_date": "2008-02-10", "episode_number": 3, "episode_type": "standard", "id": 62087, "name": "...And the Bag's in the River", "overview": "Walter fights with Jesse over his drug use, causing him to leave Walter alone with their captive, Krazy-8. Meanwhile, Hank has a scared straight moment with Walter Jr. after his aunt discovers he has been smoking pot. Also, Skylar is upset...", "production_code": "", "runtime": 49, "season_number": 1, "show_id": 1396, "still_path": "/2kBeBlxGqBOdWlKwzAxiwkfU5on.jpg", "vote_average": 0, "vote_count": 0, "crew": [ { "department": "Camera", "job": "Director of Photography", "credit_id": "52b7049c19c2953b63015013", "adult": false, "gender": 2, "id": 17948, "known_for_department": "Camera", "name": "Reynaldo Villalobos", "original_name": "Reynaldo Villalobos", "popularity": 0.904, "profile_path": "/4YlfhHDRZWhbRgeqT2Bwl1u5p9j.jpg" }, { "department": "Writing", "job": "Writer", "credit_id": "52542275760ee313280006ce", "adult": false, "gender": 2, "id": 66633, "known_for_department": "Writing", "name": "文斯·吉利根", "original_name": "文斯·吉利根", "popularity": 2.7786, "profile_path": "/wJIxATESjzsjSgvRhVavOmdamXc.jpg" }, { "department": "Directing", "job": "Director", "credit_id": "52542275760ee31328000725", "adult": false, "gender": 2, "id": 111338, "known_for_department": "Directing", "name": "亚当·伯恩斯坦", "original_name": "亚当·伯恩斯坦", "popularity": 1.0511, "profile_path": "/mnob89jXPcPfW85PPw7tTPCKSig.jpg" } ], "guest_stars": [ { "character": "Steven Gomez", "credit_id": "5271b489760ee35b3e0881a7", "order": 8, "adult": false, "gender": 2, "id": 61535, "known_for_department": "Acting", "name": "史蒂文·迈克尔·奎扎达", "original_name": "史蒂文·迈克尔·奎扎达", "popularity": 1.7511, "profile_path": "/pVYrDkwI6GWvCNL2kJhpDJfBFyd.jpg" }, { "character": "Krazy-8", "credit_id": "52725845760ee3046b09426e", "order": 504, "adult": false, "gender": 2, "id": 1046460, "known_for_department": "Acting", "name": "Max Arciniega", "original_name": "Max Arciniega", "popularity": 1.4399, "profile_path": "/eqKAJKPpt41KpsLIkkBnAY4HMAL.jpg" }, { "character": "Carmen Molina", "credit_id": "52542273760ee31328000676", "order": 643, "adult": false, "gender": 1, "id": 115688, "known_for_department": "Acting", "name": "卡门·塞兰诺", "original_name": "卡门·塞兰诺", "popularity": 1.1342, "profile_path": "/nzJEe2UqvvMIBJZP1aeFEj4EunN.jpg" } ] } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` ## Get a season `GET /3/tv/{series_id}/season/{season_number}` returns one season and its full `episodes` array in a single reply. Season numbers start at `1`, and `0` is reserved for specials. Take the series id and the season numbers from the [TV series](https://amodb.dev/tv-series/) record. The example reads season 1 of Breaking Bad. The code prints one line per episode. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/tv/1396/season/1?language=en-US'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const season = await res.json(); for (const ep of season.episodes) { console.log(String(ep.episode_number).padStart(2, '0'), ep.name, ep.air_date, `${ep.runtime ?? '?'} min`); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/tv/1396/season/1", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() season = r.json() for ep in season["episodes"]: print(f"{ep['episode_number']:02d}", ep["name"], ep["air_date"], ep["runtime"] or "?") ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $season = json_decode($body, true); foreach ($season['episodes'] as $ep) { printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']); } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Season struct { Name string `json:"name"` Episodes []struct { EpisodeNumber int `json:"episode_number"` Name string `json:"name"` AirDate string `json:"air_date"` Runtime int `json:"runtime"` } `json:"episodes"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396/season/1?language=en-US", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var s Season if err := json.NewDecoder(res.Body).Decode(&s); err != nil { panic(err) } for _, e := range s.Episodes { fmt.Printf("%02d %s %s %d min\n", e.EpisodeNumber, e.Name, e.AirDate, e.Runtime) } } ``` ### Parameters | Parameter | In | Required | Description | | -------------------- | ----- | ---------- | -------------------------------------------------------------------------------------------- | | `series_id` | path | yes | Numeric TV id, for example `1396`. | | `season_number` | path | yes | Integer season number. `0` returns specials. | | `api_key` | query | one of two | Your key. Use this or the `Authorization: Bearer` header. | | `language` | query | no | TMDB tag such as `en-US` or `fr-FR`. 14 base languages are served. Default `en-US`. | | `append_to_response` | query | no | Season level values: `credits`, `external_ids`, `images`, `videos`. Other names are ignored. | ### Response fields | Field | Type | Notes | | --------------------- | -------------- | ---------------------------------------------------------- | | `id`, `season_number` | integer | Season id and its number inside the show. | | `name`, `overview` | string | Localized text, empty when no translation exists. | | `air_date` | string or null | Date of the first episode, `YYYY-MM-DD`. | | `poster_path` | string or null | Append to `https://img.amodb.dev/t/p/{size}`. | | `vote_average` | number | Aggregate user score for the season. | | `episodes` | array | Every episode, with the fields listed in the next section. | ### Example response `GET /3/tv/1396/season/1?language=en-US`. The season has 7 episodes, so `episodes` is cut to one entry, and the `crew` and `guest_stars` arrays of that entry are left out: ```json { "air_date": "2008-01-20", "episodes": [ { "air_date": "2008-01-20", "episode_number": 1, "episode_type": "standard", "id": 62085, "name": "Pilot", "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to...", "production_code": "", "runtime": 59, "season_number": 1, "show_id": 1396, "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg", "vote_average": 0, "vote_count": 0 } ], "name": "Season 1", "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...", "id": 3572, "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 } ``` Every episode in the season reply also carries `crew` and `guest_stars` arrays, with the entry shape described on [credits](https://amodb.dev/credits/). `runtime` can be null for an unaired episode. ## Get an episode `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` returns one episode. The season reply already holds every episode with `crew` and `guest_stars`, so use this endpoint to refresh one record without reloading the season. It accepts `language` and `append_to_response` with `credits`, `external_ids`, `images`, `translations` and `videos`. A request such as `/3/tv/1396/season/1/episode/1?append_to_response=credits` costs one request. | Field | Type | Notes | | --------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer | Episode id. | | `show_id` | integer | Series id. Present in the season reply and on the series pointers, not in the single episode reply. | | `season_number`, `episode_number` | integer | Position inside the show. Use them to build the request path. | | `name`, `overview` | string | Localized text. | | `air_date` | string or null | Date only, no time or time zone. Null when unscheduled. | | `episode_type` | string | `standard` for regular episodes. To spot a finale, compare `episode_number` with the `episode_count` of that season in the series record. | | `runtime` | integer or null | Minutes. | | `production_code` | string | Studio code, often empty. | | `still_path` | string or null | Episode still. Use `w300` or `original` from `https://img.amodb.dev/t/p/{size}`. | | `vote_average`, `vote_count` | number, integer | Aggregate user score. | | `crew`, `guest_stars` | array | Credits for this episode, see [credits](https://amodb.dev/credits/). | ## Next and last episode on the series record The series endpoint returns `next_episode_to_air` and `last_episode_to_air`. Each one is an episode summary with the fields above, plus `show_id` and minus `crew` and `guest_stars`. The next one is null for ended shows and for returning shows without a confirmed date. The sample reads South Park, a returning show. ```js const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; const res = await fetch('https://api.amodb.dev/3/tv/2190', { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const next = (await res.json()).next_episode_to_air; console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode'); ``` For a countdown, compare `air_date` with the viewer's local date. The value carries no time of day, so show a date and not a clock time. ## Season and episode sub-resources Season and episode paths have their own sub-resources. Several of them return empty data today. | Method and path | Returns | | --------------------------------------------------------- | ------------------------------------------------------------------- | | `GET /tv/{series_id}/season/{season_number}/credits` | `id`, `cast` and `crew` for the season | | `GET /tv/{series_id}/season/{season_number}/images` | `id` and an empty `posters` array | | `GET /tv/{series_id}/season/{season_number}/videos` | `id` and an empty `results` array | | `GET /tv/{series_id}/season/{season_number}/external_ids` | `id` plus `tvdb_id`, `wikidata_id` and other ids, all null | | `GET /tv/{series_id}/season/{season_number}/translations` | `id` and an empty `translations` array | | `GET .../episode/{episode_number}/credits` | `id`, an empty `cast`, `crew` and `guest_stars` | | `GET .../episode/{episode_number}/images` | `id` and a `stills` array with the episode still | | `GET .../episode/{episode_number}/videos` | `id` and an empty `results` array | | `GET .../episode/{episode_number}/external_ids` | `id` plus `imdb_id`, `tvdb_id` and other ids, all null | | `GET .../episode/{episode_number}/translations` | `id` and a `translations` array with name and overview per language | Season and episode credits are covered on [credits](https://amodb.dev/credits/), and stills on [images](https://amodb.dev/images-api/). amodb does not offer the TMDB `changes` paths or an endpoint for the episodes of one episode group. ## Errors | HTTP | status_code | When | | ---- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | The key is missing or wrong. | | 402 | 36 | The plan period has ended. | | 404 | 34 | The series, season or episode does not exist, for example season `0` on a show without specials, or the path is not offered. | | 405 | 37 | You called a write method. | | 429 | 25 | Over your requests per minute. Wait for the `Retry-After` seconds. | See [errors](https://amodb.dev/errors/) for the full body format and [rate limits](https://amodb.dev/rate-limits/) for the windows. ## Practical notes - Seasons and episodes are cached for 6 hours. Re-read the current season once or twice a day while a show airs. - A 10 season show needs 10 season calls. On the 20 requests per minute plan that uses half of one minute's allowance, and a repeat run within 6 hours is answered from the edge cache. - An unaired episode can have a null `air_date`, a null `runtime` and an empty `overview`. Render a placeholder instead of failing. - Stills are wide frames, not posters. Ask for `w300` on lists and `original` only when you need a full size view. ## Questions and answers ### How do I list every episode of a show? Read number_of_seasons from the series record, then call the season endpoint once per season number. Each season reply carries its full episodes array, so a five season show takes five requests. ### What does season number 0 mean? Season 0 holds specials such as behind the scenes pieces and recaps. It exists only when the show has specials, and a show without them returns 404 with status_code 34 for season 0. ### Why is air_date null for some episodes? The episode is announced but has no confirmed date yet. Treat null as unscheduled, and check next_episode_to_air on the series record for the next dated episode. ### Can I get a DVD or absolute episode order? Not as a separate listing. GET /3/tv/{series_id}/episode_groups names the orders a show has, but amodb does not offer an endpoint that returns the episodes of one group. The season endpoint gives the standard order. ## Related pages - [TV series API](https://amodb.dev/tv-series/): TV series API with the same paths and JSON as TMDB v3. Get a show by id with seasons, networks and the next episode, plus content ratings and watch providers. - [Credits API](https://amodb.dev/credits/): Credits API with the same paths and JSON as TMDB v3. Get cast and crew for movies, series, seasons and episodes, with order, department and job fields. - [Images API and image host](https://amodb.dev/images-api/): Movie images API with TMDB v3 paths: list posters, backdrops, logos and stills per title, then load them from img.amodb.dev in 10 sizes with no key. - [Episode guide API](https://amodb.dev/episode-guide-api/): Episode guide API with TMDB v3 season and episode endpoints: names, air dates, runtimes, stills and episode group lists for any series, in 14 languages. - [Rate limits](https://amodb.dev/rate-limits/): amodb limits each key by requests per minute in a sliding 60 second window: 20, 40 or 120 by plan. Read the rate limit headers and handle 429 with Retry-After. - [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes. Updated: 2026-10-18. Source: https://amodb.dev/tv-seasons-episodes/