Discover movies (filters)
discover_moviesFind movies by complex filters: genre, year, rating, runtime, language, cast, crew, providers, keywords, certification. Solves queries like 'popular sci-fi from the 1990s on Netflix'.
Instructions
Find movies by structured filters instead of a title query: genres (include/exclude), year or release-date range, rating range, vote count, runtime range, original language, cast/crew/people, companies, keywords, watch providers, certification, a region code (minor effect only — see its own description), an adult-content toggle, and sort order. certification/with_watch_providers have validation and silent-fallback rules — see their own field descriptions. Use for 'popular sci-fi from the 1990s rated above 7 available on Netflix', or for a specific person's work in one genre — 'which of this director's/actor's/composer's films are animated' — via with_crew/with_cast/with_people + with_genres together; get_person_credits has no genre filter, so this combination is the right tool for that question, not that one. Resolve ids with get_movie_genres, search_people, search_keywords, search_companies, 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. | |
| region | No | ISO-3166-1 country code. TMDB's docs describe this as picking which country's release date counts as a movie's release date for date-based filtering (year, release_date_gte/lte) — but live testing found no measurable effect there; use certification_country instead to scope the certification filter, which does work. The one confirmed live effect: supplying any value (even one TMDB doesn't recognize) shifts total_results by a handful of titles versus omitting this field entirely, even with no other filter — real but too small and unexplained to use for precise filtering. Movie-only. | |
| sort_by | No | Sort order. Defaults to TMDB's own default (roughly popularity-based) if omitted. | |
| 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_cast | No | Comma-separated TMDB person ids, restricted to cast (actor) roles. Use search_people to resolve an actor's name to their id. | |
| with_crew | No | Comma-separated TMDB person ids, restricted to crew roles (e.g. a director). Use search_people to resolve a name to their id. | |
| 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_people | No | Comma-separated TMDB person ids, matching either a cast or crew role. Use search_people to resolve a name to their id. | |
| 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_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 |