Discover TV shows (filters)
discover_tvFilter TV shows by genre, air date, rating, runtime, network, language, keyword, watch provider, and status to pinpoint series like miniseries or ended kids' shows.
Instructions
Find TV shows by structured filters (genres, first-air year or date range, rating range, vote count, runtime, language, companies, networks, keywords, watch providers, 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 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. | |
| 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 vote average (0-10). | |
| min_rating | No | Minimum 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 | Comma-separated TMDB genre ids (AND); get ids from get_movie_genres/get_tv_genres. | |
| 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). | |
| watch_region | No | Two-letter ISO-3166-1 country code, e.g. 'US'. | |
| certification | No | Filter by exact age/content certification, e.g. 'PG-13' (movies) or 'TV-Y7' (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 | Comma-separated TMDB keyword ids (use search_keywords to resolve names → ids). | |
| with_networks | No | Comma-separated 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. | |
| with_companies | No | Comma-separated TMDB production company ids (use search_companies to resolve names → ids). | |
| 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). | |
| 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). | |
| with_watch_providers | No | Comma-separated 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. | |
| certification_country | No | Country whose certification system the `certification` filter uses, e.g. 'US'. | |
| with_original_language | No | ISO-639-1 original-language code, e.g. 'en', 'ja'. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| results | Yes | ||
| total_pages | Yes | ||
| total_results | Yes |