Discover movies (filters)
discover_moviesRead-only
Find movies by structured filters—genre, release window, rating, runtime, cast/crew, watch providers, certification, or region—without starting from a title query.
Instructions
Find movies by structured filters instead of a title query: genres (include/exclude), year or release-date range, TMDB vote-average range, vote count, runtime range, original language, cast/crew/people, companies (include/exclude), origin country, keywords (include/exclude), watch providers (include/exclude) and access model (subscription/rent/buy/free/ads), certification, a release window in one country by release type (any_release_date_gte/lte + region + with_release_type — e.g. 'movies in German cinemas this month'), an adult-content toggle, and sort order. certification/with_watch_providers/without_watch_providers/with_watch_monetization_types/with_release_type/region have validation and silent-fallback rules — see their own field descriptions. Use for 'popular sci-fi from the 1990s with a TMDB vote average 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: limits any_release_date_gte/lte (and with_release_type) to releases in this country, e.g. 'DE'. Requires any_release_date_gte or any_release_date_lte; it has no effect on year/release_date_gte/lte. An unrecognized code such as 'ZZ' matches nothing ('XX' is a real TMDB pseudo-region, not an error). 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. 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_cast | No | TMDB person ids, restricted to cast (actor) roles. Use search_people to resolve an actor's name to their id. Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| with_crew | No | TMDB person ids, restricted to crew roles (e.g. a director). Use search_people to resolve a name to their id. Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| 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_people | No | TMDB person ids, matching either a cast or crew role. Use search_people to resolve a name to their id. Join several ids with "," to require ALL of them, or "|" to match ANY (e.g. "8|9"). | |
| 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_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). | |
| with_release_type | No | Only count releases of these types toward any_release_date_gte/lte (and region): 'premiere', 'theatrical_limited', 'theatrical' (wide cinema release), 'digital' (VOD/streaming), 'physical' (DVD/Blu-ray), 'tv' (TV broadcast). Several values match ANY of them. Requires any_release_date_gte or any_release_date_lte. | |
| 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. | |
| any_release_date_gte | No | Only movies with at least one release (any country and release type, re-releases included) on/after this date (YYYY-MM-DD) — unlike release_date_gte, which uses each movie's original premiere date. Narrow it with region and with_release_type, e.g. region='DE' + with_release_type=['theatrical'] + this window = movies in German cinemas then. A re-released movie matches, but its row's release_date stays the original one. Must be <= any_release_date_lte if both are given. | |
| any_release_date_lte | No | Only movies with at least one release (see any_release_date_gte) on/before this date (YYYY-MM-DD). | |
| 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 |