# themoviedb.org API: List upcoming theatrical movies in a country > Lists movies scheduled for theatrical release in a country over the coming three weeks, soonest first, from TMDB's country-specific release calendar, with genres, overview and user score. Unofficial. Not affiliated with or endorsed by themoviedb.org. - Page: https://fous.com/methods/themoviedb.org/list-upcoming-movies - Method: `themoviedb.org/list_upcoming_movies`, version 1 - Website: themoviedb.org - Returns: title, release date, genres, overview, user score, poster link, TMDB link - Effect: read (it gets data and changes nothing) - Sign-in: none needed - Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free - Verified: Nov 2, 2026 ## Inputs | Field | Type | Required | In the run below | Description | |---|---|---|---|---| | `country` | string | no | `"United States"` | Country name or two-letter country code, such as United States or US. Default "United States". | | `max_results` | integer | no | `20` | Maximum movies to return, such as 20 (up to 100). Default 20. | ## Output From a run on Oct 31, 2026, shortened. Its input: ```json { "country": "United States", "max_results": 20 } ``` Its output: ```json { "movies": [ { "title": "NAZA", "genres": [ "Documentary" ], "overview": "In secret conversations on the rooftops of Tel Aviv at night, the systems behind Israel's calculated mass killing of Palestinian civilians in Gaza are revealed by the people who designed and operated them.", "tmdb_link": "https://www.themoviedb.org/movie/1755291-naza", "poster_link": "https://media.themoviedb.org/t/p/w116_and_h174_face/uLsG2CW8oHnmXWdtPyruSegI8rF.jpg", "release_date": "2026-09-30", "user_score_percent": 78 }, { "title": "LINKIN PARK: UNSHATTER", "genres": [ "Music", "Documentary" ], "overview": "After a seven-year hiatus following the devastating loss of their beloved bandmate Chester Bennington, LINKIN PARK'S remaining members struggled to find their way forward. Their shared history and enduring friendship, combined with the fresh perspective of two new band members Emily Armstrong and Co…", "tmdb_link": "https://www.themoviedb.org/movie/1388805-linkin-park-unshatter", "poster_link": "https://media.themoviedb.org/t/p/w116_and_h174_face/kHNrz7DBVPrtyMhJxmBm2poS2l9.jpg", "release_date": "2026-09-30", "user_score_percent": null }, { "title": "Loretta Robinson:An American Dream", "genres": [], "overview": "Joh'Vonnie Monroe:An American Dream is a film of how Joh'Vonnie Monroe got started,what achievements and records she has shattered and the barriers she broke for all black girls and woman to play The Good Witch Of The South she first gained the role in the film The Wonderful Wizard Of Ha's on TMDB f…", "tmdb_link": "https://www.themoviedb.org/movie/1700118-loretta-robinson-an-american-dream", "poster_link": "https://media.themoviedb.org/t/p/w116_and_h174_face/thNKjMCyIsayMZPYfFt7bhGpkYk.jpg", "release_date": "2026-09-30", "user_score_percent": null } ] } ``` ## Run it From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output: ```bash curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"themoviedb.org/list_upcoming_movies","input":{"country":"United States","max_results":20}}' ``` From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`. ## Ask your agent - What movies are coming out in theaters in Germany over the next few weeks? - Show me the next 10 films hitting UK cinemas soon, with genres and a short plot summary for each - Using TMDB, list upcoming theatrical releases in Japan for the next three weeks, earliest first - I'm planning movie nights in Canada — which new releases open in cinemas soon, and what are their user ratings? - Pull up to 50 upcoming movie premieres in Brazil from themoviedb.org with release dates and poster links ## Input schema ```json { "type": "object", "required": [], "properties": { "country": { "type": "string", "default": "United States", "description": "Country name or two-letter country code, such as United States or US." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum movies to return, such as 20 (up to 100)." } } } ``` ## Output schema ```json { "type": "object", "required": [ "movies" ], "properties": { "movies": { "type": "array", "items": { "type": "object", "required": [ "title", "release_date", "genres", "overview", "user_score_percent", "poster_link", "tmdb_link" ], "properties": { "title": { "type": "string" }, "genres": { "type": "array", "items": { "type": "string" } }, "overview": { "type": [ "string", "null" ] }, "tmdb_link": { "type": "string" }, "poster_link": { "type": [ "string", "null" ] }, "release_date": { "type": "string", "format": "date" }, "user_score_percent": { "type": [ "integer", "null" ] } }, "additionalProperties": false }, "description": "Upcoming theatrical movies sorted by release date in the selected country." } }, "additionalProperties": false } ``` ## See more - [themoviedb.org API: Get movie details](https://fous.com/methods/themoviedb.org/get-movie.md): Finds a movie on TMDB by exact title (optionally its release year) or by TMDB movie link, and returns its details, cast, crew, trailers, and the release date, age rating and streaming services for a chosen country. - [themoviedb.org API: List trending movies and TV shows](https://fous.com/methods/themoviedb.org/list-trending.md): Lists TMDB homepage trending titles for today or this week in displayed order, with year, user score, overview and poster. The homepage shows up to 20 mixed movie and TV titles per period; the movie and TV filters select from those. - [themoviedb.org API: Get TV show details](https://fous.com/methods/themoviedb.org/get-tv-show.md): Finds a TV show on TMDB by exact name or TMDB show link and returns its details, cast, seasons, the last aired and next scheduled episodes, and the streaming services listed for a chosen country. - [Fandango API: List movies now playing or coming soon](https://fous.com/methods/fandango.com/list-now-playing.md): Lists Fandango movies now playing or coming soon in U.S. theaters, in Fandango's order, with release dates, age ratings, runtimes and Rotten Tomatoes scores when shown. - [Rotten Tomatoes API: List movies](https://fous.com/methods/rottentomatoes.com/list-movies.md): Lists Rotten Tomatoes movies in theaters, coming soon, or at home, by genre and site sort order, with scores, release dates, age ratings, posters and links. - [Box Office Mojo API: Get weekend box office chart](https://fous.com/methods/boxofficemojo.com/get-weekend-box-office.md): Returns ranked box office grosses for a weekend in a market. Defaults to the latest reported US and Canada weekend; international markets use their own weekend calendar. - [Fandango API: Get movie showtimes](https://fous.com/methods/fandango.com/get-movie-showtimes.md): Finds a movie's showtimes at nearby US theaters on Fandango, with formats, local times and ticket links. - [JustWatch API: List streaming chart titles](https://fous.com/methods/justwatch.com/list-streaming-charts.md): Lists titles on JustWatch's daily streaming chart for a country, optionally limited to one streaming service. - [All themoviedb.org methods](https://fous.com/methods/themoviedb.org.md)