Discover TV shows (filters)
discover_tvRead-only
Filter TV shows by genre, air date, rating, network, streaming provider, status, or certification to build structured discovery queries; cast and crew searches are excluded—use person credits for actor lookups.
Instructions
Find TV shows by structured filters (genres (include/exclude), first-air year or date range, TMDB vote-average range, vote count, runtime, language, origin country, companies (include/exclude), networks, keywords (include/exclude), watch providers (include/exclude) and access model (subscription/rent/buy/free/ads), episodes airing in a date range (air_date_gte/lte), type, status, certification, an adult-content toggle, sort) — but NOT cast/crew/person: this tool doesn't accept those params for TV at all (calling with them is a validation error, not a silent no-op) because TMDB's own /discover/tv would silently ignore them anyway, unlike /discover/movie; to find TV shows featuring someone, call get_person_credits instead and filter its results to media_type 'tv'. certification/with_watch_providers/without_watch_providers/with_watch_monetization_types have validation and silent-fallback rules — see their own field descriptions. The TV counterpart of discover_movies; use with_networks for 'HBO shows', with_type='Miniseries' for short/limited series (e.g. 'best miniseries to binge in a weekend'), with_status='Ended' to exclude shows still airing, certification='TV-Y7' + certification_country='US' for 'shows appropriate for a young kid'. Resolve ids with get_tv_genres, search_companies, search_keywords, search_watch_providers.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number for pagination (TMDB returns up to 20 results per page, max 500). | |
| year | No | Release / first-air year. | |
| sort_by | No | Sort order. Defaults to TMDB's own default (roughly popularity-based) if omitted. TV's vocabulary differs from discover_movies' — 'name'/'first_air_date' instead of 'original_title'/'primary_release_date', and no 'revenue' (TMDB doesn't track it per-show). | |
| language | No | Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name. | |
| min_votes | No | Minimum vote count (filters obscure titles). | |
| with_type | No | Restrict to this TV type — e.g. 'Miniseries' for short/limited series, excluding documentaries/reality/talk shows/etc. that would otherwise mix into a genre/rating search. | |
| max_rating | No | Maximum TMDB vote average (0-10). | |
| min_rating | No | Minimum TMDB vote average (0-10). Must be <= max_rating if both are given. | |
| max_runtime | No | Maximum runtime in minutes. | |
| min_runtime | No | Minimum runtime in minutes. Must be <= max_runtime if both are given. | |
| with_genres | No | TMDB genre ids; get them from get_movie_genres/get_tv_genres. Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| with_status | No | Restrict to this production status, e.g. 'Ended' to exclude shows still airing (a still-airing show's later seasons could still be mediocre or unfinished). | |
| air_date_gte | No | Only shows with an episode airing on/after this date (YYYY-MM-DD) — e.g. 'what's airing this week' with air_date_lte; unlike release_date_gte, which uses the show's first air date. Dates are US Eastern time. Must be <= air_date_lte if both are given. | |
| air_date_lte | No | Only shows with an episode airing on/before this date (YYYY-MM-DD), see air_date_gte. | |
| watch_region | No | Two-letter ISO-3166-1 country code, e.g. 'US', whose streaming catalog with_watch_providers / without_watch_providers / with_watch_monetization_types filter on. Only valid together with at least one of them. | |
| certification | No | Filter by exact age/content certification, e.g. 'PG-13' (movies) or 'TV-Y7' (TV); join several with '|' to match ANY of them, e.g. 'G|PG' for kids/family movies or 'TV-Y|TV-Y7|TV-G' for kids' TV. Requires certification_country, and a certification_country TMDB doesn't recognize silently disables this filter (returns unfiltered results) instead of erroring or matching nothing — double-check the country actually has data for that rating system. Matching is case-insensitive (verified live: 'pg-13' and 'PG-13' return identical results) but must otherwise exactly match one of TMDB's known rating strings for that country's system, punctuation included (e.g. 'PG-13', not 'PG13'). Unlike get_movie/get_tv's own certification field (which falls back to the US rating, then any country, when the requested region has none), this filter has NO fallback: a title with no certification entry at all for the exact country given is silently excluded from results, even if it's certified elsewhere (e.g. has a US rating) — for a country with sparse TMDB certification data, prefer certification_country='US' for broader, more reliable coverage over the user's actual country if completeness matters more than exact local ratings. | |
| include_adult | No | Include adult (NSFW) results. Defaults to false. | |
| with_keywords | No | TMDB keyword ids (use search_keywords to resolve names → ids). Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| with_networks | No | TMDB TV network ids, e.g. HBO=49, Netflix=213 (verified live). Unlike with_companies/with_keywords/with_people, this server has no name-based resolver for networks — supply the raw TMDB network id directly; a well-known network's id may already be known, otherwise there's no in-server way to look one up. Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| with_companies | No | TMDB production company ids (use search_companies to resolve names → ids). Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| without_genres | No | Comma-separated TMDB genre ids to exclude; get ids from get_movie_genres/get_tv_genres. | |
| release_date_gte | No | Only entries released on/after this date (YYYY-MM-DD). Must be <= release_date_lte if both are given. | |
| release_date_lte | No | Only entries released on/before this date (YYYY-MM-DD). | |
| without_keywords | No | Comma-separated TMDB keyword ids to exclude (use search_keywords to resolve names → ids). | |
| without_companies | No | Comma-separated TMDB production company ids to exclude: titles produced by ANY of them are dropped (use search_companies to resolve names → ids). | |
| with_origin_country | No | Only titles whose country of origin (where they were produced, not where they can be watched) is one of these ISO-3166-1 codes, e.g. ['KR'] for Korean titles; several codes match ANY of them. An unrecognized code such as 'ZZ' matches nothing. | |
| with_watch_providers | No | TMDB watch-provider ids (use search_watch_providers to resolve a service name, e.g. 'Netflix', to its numeric id); requires watch_region to also be set. Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| certification_country | No | Country whose certification system the `certification` filter uses, e.g. 'US'. Only valid together with certification. | |
| with_original_language | No | ISO-639-1 original-language code, e.g. 'en', 'ja'. | |
| without_watch_providers | No | Comma-separated TMDB watch-provider ids to exclude: titles that ANY of them offers in watch_region are dropped, e.g. 'not on Netflix' (use search_watch_providers to resolve a service name to its id); requires watch_region to also be set. | |
| with_watch_monetization_types | No | Only titles available in watch_region through at least one of these access models: 'flatrate' = included in a subscription (e.g. Netflix), 'free' = free to watch, 'ads' = free with ads, 'rent' = paid rental, 'buy' = paid purchase. Several values match ANY of them. Requires watch_region; works alone (any provider). Combined with with_watch_providers, TMDB checks the two independently, not per provider: with_watch_providers=2 (Apple TV, rent/buy only) + 'flatrate' still matches titles rentable on Apple TV that some OTHER service streams — check get_watch_providers to confirm which service offers which access model. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| results | Yes | ||
| total_pages | Yes | ||
| total_results | Yes |