themoviedb.org API: List trending movies and TV shows
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.
Unofficial. Not affiliated with or endorsed by themoviedb.org.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- What optional
what Which trending titles to include, for example movies. People are not listed on the public trending homepage.
all
One of
all,movies,tv. Defaultall.- Period optional
period Time period to display, for example this_week.
today
One of
today,this_week. Defaulttoday.- Max Results optional
max_results Maximum number of entries to return, for example 10. The public homepage lists only 20 mixed titles per period.
5
Whole number from 1 to 100. Default
20.
Input as JSON
{ "what": "all", "period": "today", "max_results": 5}Output
{ "trending": [ { "rank": 1, "type": "movie", "year": 2026, "title": "Runner", "overview": "A former soldier is thrown into a brutal race against time when a critical medical delivery makes him and his unlikely partner the targets of a ruthless cartel. As the mission spirals into a deadly manhunt, every detour, delay, and bullet pushes them closer to failure. With betrayal closing in from …", "tmdb_link": "https://www.themoviedb.org/movie/1377237-runner" , "user_score": 77, "poster_link": "https://media.themoviedb.org/t/p/w220_and_h330_face/yBKMAIj7clP42UkFejhGDBBoTpb.jpg" }, { "rank": 2, "type": "TV show", "year": 2026, "title": "Lanterns", "overview": "Two intergalactic cops, new recruit John Stewart and Lantern legend Hal Jordan, are drawn into a dark, Earth-based mystery as they investigate a murder in the American heartland.", "tmdb_link": "https://www.themoviedb.org/tv/95350-lanterns" , "user_score": 83, "poster_link": "https://media.themoviedb.org/t/p/w220_and_h330_face/gpC7h43xPMEV3goYMQShfJbTtLq.jpg" }, { "rank": 3, "type": "movie", "year": 2026, "title": "Digger", "overview": "The most powerful man in the world embarks on a frantic mission to prove he is humanity's savior before the disaster he's unleashed destroys everything.", "tmdb_link": "https://www.themoviedb.org/movie/1248832-digger" , "user_score": 81, "poster_link": "https://media.themoviedb.org/t/p/w220_and_h330_face/1ATXKrIPJyKNwnJ6lcG088Sa6zi.jpg" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"themoviedb.org/list_trending","input":{"what":"all","period":"today","max_results":5}}' # 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_trending" , "input": { "what": "all", "period": "today", "max_results": 5 }})# 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_trending" , "input": { "what": "all", "period": "today", "max_results": 5 } }), 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_trending# with {"what":"all","period":"today","max_results":5}"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": { "what": { "enum": [ "all", "movies", "tv" ], "type": "string", "default": "all", "description": "Which trending titles to include, for example movies. People are not listed on the public trending homepage." }, "period": { "enum": [ "today", "this_week" ], "type": "string", "default": "today", "description": "Time period to display, for example this_week." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum number of entries to return, for example 10. The public homepage lists only 20 mixed titles per period." } }}Output schema
{ "type": "object", "required": [ "trending" ], "properties": { "trending": { "type": "array", "items": { "type": "object", "required": [ "rank", "title", "year", "type", "user_score", "overview", "poster_link", "tmdb_link" ], "properties": { "rank": { "type": "integer", "description": "Position on the homepage trending list." }, "type": { "enum": [ "movie", "TV show" ], "type": "string", "description": "Type of title." }, "year": { "type": [ "integer", "null" ], "description": "Release or premiere year, if available." }, "title": { "type": "string", "description": "Movie or show title." }, "overview": { "type": [ "string", "null" ], "description": "Summary from the title page." }, "tmdb_link": { "type": "string", "description": "Title page link." }, "user_score": { "type": [ "integer", "null" ], "description": "TMDB user score as a percentage." }, "poster_link": { "type": [ "string", "null" ], "description": "Poster image link." } }, "additionalProperties": false }, "description": "Titles in the homepage trending order." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
themoviedb.org/list_trending- Returns
- rank, title, year, type, user score, overview, 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_trending with the inputs above.
Ask your agent
- What are the top 10 trending movies on TMDB this week? Include their user scores and a short synopsis.
- Show me which TV shows are trending today, with their release year and poster images.
- I need a ranked list of what's hot right now in film and television today, both movies and series mixed together, with links to each title.
- Give me the 5 most popular trending series this week along with their ratings and overviews.
- Pull the full trending list from themoviedb.org for this week, mixed movies and TV, showing rank, type, and score.
See more
All themoviedb.org methodsLists 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.
themoviedb.org/list_upcoming_moviesFinds 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_movieFinds 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 Letterboxd films in popularity order for a week, month, year or all time, optionally filtered by genre and decade. Ratings and posters may be unavailable for some films.
letterboxd.com/list_popular_filmsLists titles in an IMDb movie or TV chart (Top 250 movies, Top 250 TV shows, most popular movies or TV shows) with ratings, votes, runtime, age rating and weekly rank movement for popularity charts. Popular charts contain up to 100 titles.
imdb.com/list_top_chartsLists up to 25 public repositories trending on GitHub, in page order, optionally filtered by programming language and time period.
github.com/list_trending_repositoriesLists MyAnimeList's top anime in rank order for a selected ranking (all, airing, upcoming, TV, movies or most popular), with English title, score, type, episodes, airing dates and members.
myanimelist.net/list_top_animeLists Google Trends 'Trending now' searches for a country, time window and category, in Google's order. Each search comes with its volume, activity, related searches and news headlines.
trends.google.com/list_trending_searches