---
title: "Get a Letterboxd popularity-ranked film chart"
method: GET
path: "/letterboxd/popular"
tags: ["Letterboxd"]
---

# Get a Letterboxd popularity-ranked film chart

`GET /letterboxd/popular`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/letterboxd/popular`
- Auth: API key in header `x-api-key`

Returns a Letterboxd film chart ranked by popularity. Omit `period` for all-time, or set `day`, `week`, `month` or `year`. `genre` takes a genre slug, `decade` a value like `2010s`, and `limit` defaults to 10 with a max of 50. Each film has its `slug`, title and Letterboxd URL.

## Query parameters

- `period` 'day' | 'week' | 'month' | 'year'
- `genre` string
- `decade` string
- `limit` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- LetterboxdPopularResponseDoc
  - `code` integer
  - `data` LetterboxdPopularResponse
    - `decade` string: Decade filter that was applied, for example `2010s`. Omitted when none was set.
    - `films` LetterboxdFilmRef[]: Films in the chart, most popular first.
      - `slug` string: Letterboxd film slug. Use it with the film endpoint for full detail.
      - `title` string: Title of the film.
      - `uri` string: Link to the film's page on Letterboxd.
    - `genre` string: Genre filter that was applied. Omitted when none was set.
    - `period` string: Time window of the chart: `day`, `week`, `month` or `year`. Omitted for the all-time chart.
    - `source_url` string: URL the data was read from.
  - `msg` string

## Other responses

- `400`: Bad Request
- `500`: Internal Server Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/028417aa35bb?raw)