# Letterboxd API: List popular films

> Lists 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.

Unofficial. Not affiliated with or endorsed by Letterboxd.

- Page: https://fous.com/methods/letterboxd.com/list-popular-films
- Method: `letterboxd.com/list_popular_films`, version 1
- Website: letterboxd.com
- Returns: rank, title, year, average rating, poster link, Letterboxd 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 |
|---|---|---|---|---|
| `genre` | string | no |  | Film genre, for example horror; use all for any genre. Default "all". |
| `decade` | string | no |  | Release decade, for example 1990s; use all for any decade. Default "all". |
| `period` | string | no | `"this_month"` | Popularity period, for example this_month. One of "this_week", "this_month", "this_year", "all_time". Default "this_week". |
| `max_results` | integer | no | `100` | Maximum number of films to return, for example 36. Default 36. |

## Output

From a run on Oct 31, 2026, shortened. Its input:

```json
{
  "period": "this_month",
  "max_results": 100
}
```

Its output:

```json
{
  "films": [
    {
      "rank": 1,
      "year": 2026,
      "title": "Resident Evil",
      "poster_link": "https://a.ltrbxd.com/resized/film-poster/1/3/0/2/7/1/7/1302717-untitled-resident-evil-reboot-0-70-0-105-crop.jpg?v=a688bf1bc7",
      "average_rating": 3.78,
      "letterboxd_link": "https://letterboxd.com/film/resident-evil-2026/"
    },
    {
      "rank": 2,
      "year": 2026,
      "title": "Coyote vs. Acme",
      "poster_link": "https://a.ltrbxd.com/resized/film-poster/1/0/8/9/0/8/8/1089088-coyote-vs-acme-0-70-0-105-crop.jpg?v=735eb10cc7",
      "average_rating": 3.84,
      "letterboxd_link": "https://letterboxd.com/film/coyote-vs-acme/"
    },
    {
      "rank": 3,
      "year": 2026,
      "title": "The Love Hypothesis",
      "poster_link": "https://a.ltrbxd.com/resized/film-poster/9/3/1/1/8/1/931181-the-love-hypothesis-0-70-0-105-crop.jpg?v=b925aa1882",
      "average_rating": 3.23,
      "letterboxd_link": "https://letterboxd.com/film/the-love-hypothesis/"
    }
  ]
}
```

## 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":"letterboxd.com/list_popular_films","input":{"period":"this_month","max_results":100}}'
```

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 are the most popular horror films on Letterboxd this week? Give me the top 20 with their average ratings.
- Show me the 50 most-watched 1980s science fiction movies of all time, with year and rating for each.
- Which comedies from the 2010s are trending this month? I'd like posters and links too.
- Top 10 most popular films right now on Letterboxd, any genre or decade.
- I need a ranked list of the most popular 1970s dramas this year, around 30 titles, including average rating.

## Input schema

```json
{
  "type": "object",
  "properties": {
    "genre": {
      "type": "string",
      "default": "all",
      "description": "Film genre, for example horror; use all for any genre."
    },
    "decade": {
      "type": "string",
      "default": "all",
      "description": "Release decade, for example 1990s; use all for any decade."
    },
    "period": {
      "enum": [
        "this_week",
        "this_month",
        "this_year",
        "all_time"
      ],
      "type": "string",
      "default": "this_week",
      "description": "Popularity period, for example this_month."
    },
    "max_results": {
      "type": "integer",
      "default": 36,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum number of films to return, for example 36."
    }
  }
}
```

## Output schema

```json
{
  "type": "object",
  "required": [
    "films"
  ],
  "properties": {
    "films": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "rank",
          "title",
          "year",
          "average_rating",
          "poster_link",
          "letterboxd_link"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "description": "Rank in popularity for the selected filters."
          },
          "year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "title": {
            "type": "string"
          },
          "poster_link": {
            "type": [
              "string",
              "null"
            ]
          },
          "average_rating": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average rating out of 5."
          },
          "letterboxd_link": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}
```

## See more

- [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.
- [IMDb API: List top charts](https://fous.com/methods/imdb.com/list-top-charts.md): Lists 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.
- [Netflix API: List most popular titles](https://fous.com/methods/netflix.com/list-most-popular.md): Lists Netflix's all-time most popular movies or TV shows by views in their first 91 days, with views, hours viewed and runtime.
- [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: List top grossing movies](https://fous.com/methods/boxofficemojo.com/list-top-grossing-movies.md): Lists the highest-grossing movies of a calendar year, ranked by domestic or worldwide gross, with release dates and distributors.
- [MyAnimeList API: List top anime](https://fous.com/methods/myanimelist.net/list-top-anime.md): Lists 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.
- [Netflix API: List weekly Top 10](https://fous.com/methods/netflix.com/list-top-10.md): Gets Netflix's weekly Top 10 movies or TV shows worldwide (English or non-English lists, with views, hours viewed and runtime) or in one country (ranks and weeks in the Top 10 only) for the latest published week or the Monday-to-Sunday week containing a given date.
- [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.