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.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Country optional
country Country name or two-letter country code, such as United States or US.
United States
Default
United States.- Max Results optional
max_results Maximum movies to return, such as 20 (up to 100).
20
Whole number from 1 to 100. Default
20.
Input as JSON
{ "country": "United States", "max_results": 20}Output
{ "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 } ]}Code
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}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "themoviedb.org/list_upcoming_movies" , "input": { "country": "United States", "max_results": 20 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "themoviedb.org/list_upcoming_movies" , "input": { "country": "United States", "max_results": 20 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run themoviedb.org/list_upcoming_movies# with {"country":"United States","max_results":20}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "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
{ "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}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
themoviedb.org/list_upcoming_movies- Returns
- title, release date, genres, overview, user score, poster link, TMDB link
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method themoviedb.org/list_upcoming_movies with the inputs above.
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
See more
All themoviedb.org methodsFinds 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/get_movieLists 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/list_trendingFinds 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.
themoviedb.org/get_tv_showLists 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.
fandango.com/list_now_playingLists 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.
rottentomatoes.com/list_moviesReturns 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.
boxofficemojo.com/get_weekend_box_officeFinds a movie's showtimes at nearby US theaters on Fandango, with formats, local times and ticket links.
fandango.com/get_movie_showtimesLists titles on JustWatch's daily streaming chart for a country, optionally limited to one streaming service.
justwatch.com/list_streaming_charts