Discover TV shows (filters)
discover_tvFilter TV shows by genre, air date, rating, runtime, language, country, network, keywords, streaming availability, access model, status, and certification to identify matching series.
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. Not cast/crew/person: this tool doesn't accept those params for TV at all (a validation error, not a silent no-op), because TMDB's own /discover/tv would silently ignore them, unlike /discover/movie. To find TV shows featuring someone, call get_person_credits and filter its results to media_type 'tv'. certification/certification_country/watch_region have pairing 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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "discover_tv"
}
}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 | Response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. 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. | en-US |
| 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 ('Cancelled' is a separate status, so 'Ended' alone leaves cancelled shows out). | |
| 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 | The user's country (pass it when known), whose streaming catalog with_watch_providers / without_watch_providers / with_watch_monetization_types filter on. Only valid together with at least one of them. Omitted with a watch filter set, it is 'US' (the server's TMDB_REGION). | |
| 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; one TMDB doesn't recognize silently disables this filter (returns unfiltered results) instead of erroring or matching nothing, so check the country has data for that rating system. Matching is case-insensitive (checked live: 'pg-13' and 'PG-13' return identical results) but otherwise must 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 for the exact country given is silently excluded, 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 if completeness matters more than exact local ratings. | |
| include_adult | No | Include adult (NSFW) results. | |
| with_keywords | No | TMDB keyword ids (use search_keywords to resolve names → ids, or take them from a title's `keywords` in get_movie/get_tv). 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 (checked 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), offered in watch_region. 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). | |
| 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. 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 (it reports 'flatrate' as `streaming`). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| results | Yes | ||
| total_pages | Yes | ||
| total_results | Yes |