discover_movies
Find movies using advanced filters including genre, release date, rating, language, cast, crew, and streaming availability to curate personalized film recommendations.
Instructions
Performs advanced discovery of movies with extensive filtering options. Input: Optional parameters including language (ISO 639-1), region (ISO 3166-1), sort_by, certifications, release dates, genres, keywords, watch providers, vote counts, etc. Output: JSON with paginated results. Purpose: Enable complex, criteria-based movie discovery for AI-driven content curation.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| certification | No | Filter by certification (e.g., PG-13) | |
| certification.gte | No | Certification greater than or equal to | |
| certification.lte | No | Certification less than or equal to | |
| certification_country | No | Certification country (ISO 3166-1) | |
| include_adult | No | Include adult titles (default false) | |
| include_video | No | Include items with videos | |
| language | No | ISO 639-1 language (e.g., en-US) | |
| page | No | Page number (1-500) | |
| primary_release_date.gte | No | Primary release date from (YYYY-MM-DD) | |
| primary_release_date.lte | No | Primary release date to (YYYY-MM-DD) | |
| primary_release_year | No | Primary release year | |
| region | No | ISO 3166-1 region (e.g., US) | |
| release_date.gte | No | Release date from (YYYY-MM-DD) | |
| release_date.lte | No | Release date to (YYYY-MM-DD) | |
| screened_theatrically | No | Filter for movies screened theatrically | |
| sort_by | No | Sort by (e.g., popularity.desc, release_date.desc, vote_average.desc, primary_release_date.desc, revenue.desc, original_title.asc) | |
| vote_average.gte | No | Minimum vote average (0-10) | |
| vote_average.lte | No | Maximum vote average (0-10) | |
| vote_count.gte | No | Minimum vote count | |
| vote_count.lte | No | Maximum vote count | |
| watch_region | No | ISO 3166-1 region for watch providers | |
| with_cast | No | Comma-separated person IDs | |
| with_companies | No | Comma-separated company IDs | |
| with_crew | No | Comma-separated person IDs | |
| with_genres | No | Comma-separated genre IDs | |
| with_keywords | No | Comma-separated keyword IDs | |
| with_original_language | No | Original language (ISO 639-1) | |
| with_people | No | Comma-separated person IDs | |
| with_release_type | No | Comma-separated release types (e.g., 2|3). TMDB expects bitmask but pipe is accepted by API | |
| with_release_type.gte | No | Min release type mask (advanced) | |
| with_release_type.lte | No | Max release type mask (advanced) | |
| with_runtime.gte | No | Runtime min (minutes) | |
| with_runtime.lte | No | Runtime max (minutes) | |
| with_status | No | Comma-separated status (Rumored|Planned|In Production|Post Production|Released|Canceled) | |
| with_type | No | Comma-separated movie types (Documentary, etc.) | |
| with_watch_monetization_types | No | Comma-separated monetization types (flatrate|free|ads|rent|buy) | |
| with_watch_providers | No | Comma-separated watch provider IDs | |
| without_companies | No | Comma-separated company IDs to exclude | |
| without_genres | No | Comma-separated genre IDs to exclude | |
| without_keywords | No | Comma-separated keyword IDs to exclude |
Input Schema (JSON Schema)
{
"properties": {
"certification": {
"description": "Filter by certification (e.g., PG-13)",
"type": "string"
},
"certification.gte": {
"description": "Certification greater than or equal to",
"type": "string"
},
"certification.lte": {
"description": "Certification less than or equal to",
"type": "string"
},
"certification_country": {
"description": "Certification country (ISO 3166-1)",
"type": "string"
},
"include_adult": {
"description": "Include adult titles (default false)",
"type": "boolean"
},
"include_video": {
"description": "Include items with videos",
"type": "boolean"
},
"language": {
"description": "ISO 639-1 language (e.g., en-US)",
"type": "string"
},
"page": {
"description": "Page number (1-500)",
"minimum": 1,
"type": "number"
},
"primary_release_date.gte": {
"description": "Primary release date from (YYYY-MM-DD)",
"type": "string"
},
"primary_release_date.lte": {
"description": "Primary release date to (YYYY-MM-DD)",
"type": "string"
},
"primary_release_year": {
"description": "Primary release year",
"type": "number"
},
"region": {
"description": "ISO 3166-1 region (e.g., US)",
"type": "string"
},
"release_date.gte": {
"description": "Release date from (YYYY-MM-DD)",
"type": "string"
},
"release_date.lte": {
"description": "Release date to (YYYY-MM-DD)",
"type": "string"
},
"screened_theatrically": {
"description": "Filter for movies screened theatrically",
"type": "boolean"
},
"sort_by": {
"description": "Sort by (e.g., popularity.desc, release_date.desc, vote_average.desc, primary_release_date.desc, revenue.desc, original_title.asc)",
"type": "string"
},
"vote_average.gte": {
"description": "Minimum vote average (0-10)",
"type": "number"
},
"vote_average.lte": {
"description": "Maximum vote average (0-10)",
"type": "number"
},
"vote_count.gte": {
"description": "Minimum vote count",
"type": "number"
},
"vote_count.lte": {
"description": "Maximum vote count",
"type": "number"
},
"watch_region": {
"description": "ISO 3166-1 region for watch providers",
"type": "string"
},
"with_cast": {
"description": "Comma-separated person IDs",
"type": "string"
},
"with_companies": {
"description": "Comma-separated company IDs",
"type": "string"
},
"with_crew": {
"description": "Comma-separated person IDs",
"type": "string"
},
"with_genres": {
"description": "Comma-separated genre IDs",
"type": "string"
},
"with_keywords": {
"description": "Comma-separated keyword IDs",
"type": "string"
},
"with_original_language": {
"description": "Original language (ISO 639-1)",
"type": "string"
},
"with_people": {
"description": "Comma-separated person IDs",
"type": "string"
},
"with_release_type": {
"description": "Comma-separated release types (e.g., 2|3). TMDB expects bitmask but pipe is accepted by API",
"type": "string"
},
"with_release_type.gte": {
"description": "Min release type mask (advanced)",
"type": "number"
},
"with_release_type.lte": {
"description": "Max release type mask (advanced)",
"type": "number"
},
"with_runtime.gte": {
"description": "Runtime min (minutes)",
"type": "number"
},
"with_runtime.lte": {
"description": "Runtime max (minutes)",
"type": "number"
},
"with_status": {
"description": "Comma-separated status (Rumored|Planned|In Production|Post Production|Released|Canceled)",
"type": "string"
},
"with_type": {
"description": "Comma-separated movie types (Documentary, etc.)",
"type": "string"
},
"with_watch_monetization_types": {
"description": "Comma-separated monetization types (flatrate|free|ads|rent|buy)",
"type": "string"
},
"with_watch_providers": {
"description": "Comma-separated watch provider IDs",
"type": "string"
},
"without_companies": {
"description": "Comma-separated company IDs to exclude",
"type": "string"
},
"without_genres": {
"description": "Comma-separated genre IDs to exclude",
"type": "string"
},
"without_keywords": {
"description": "Comma-separated keyword IDs to exclude",
"type": "string"
}
},
"type": "object"
}