# Letterboxd Scraper (`crawlerbros/letterboxd-scraper`) Actor

Scrape Letterboxd, the cinephile community's film database. Pull film metadata (directors, cast, genres, runtime, ratings, tagline), search by title, browse popular films, or fetch a member's profile. Pure HTTP, no login required.

- **URL**: https://apify.com/crawlerbros/letterboxd-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Developer tools, Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 17 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Letterboxd Scraper

Scrape **Letterboxd** — the cinephile community's film database. Pull rich metadata for any film (directors, cast, genres, runtime, average rating, ratings count, tagline, plot summary, languages, countries), search films by title, browse popular films and lists, scrape film reviews, browse films by director / actor / studio / country, or fetch a member's profile with their public stats and watchlist. No login, no cookies required.

Letterboxd's React frontend is fronted by Cloudflare; the actor uses Chrome 131 TLS impersonation to fetch the public-by-default pages exactly as a browser would.

### Modes

| Mode | What it returns |
| --- | --- |
| `film` | Full metadata for one or more film slugs (`recordType=film`) |
| `search` | Films matching a title query (`recordType=film`) |
| `userProfile` | Public profile + activity stats (`recordType=user`) |
| `lists` | Popular lists index OR contents of a single list (`recordType=list` + `recordType=film`) |
| `popular` | Films ranked by popularity in a chosen window (week / month / year / all-time) |
| `filmReviews` | Reviews for a film (paginated, sorted by activity) (`recordType=review`) |
| `byCrew` | Films attached to a director, actor, studio, or country (`recordType=crewMember` + `recordType=film`) |
| `userWatchlist` | A user's public watchlist, paginated (`recordType=film`) |

### What you get

#### Film records (`recordType=film`)

| Field | Description |
| --- | --- |
| `slug` | Letterboxd film slug (`parasite-2019`) |
| `url` | Public film URL |
| `title` | Film title |
| `year` | Release year |
| `directors` | Array of director names |
| `cast` | Array of leading cast names (top ~10) |
| `genres` | Array of genres (e.g. `Drama`, `Thriller`) |
| `countries` | Array of country names |
| `productionCompanies` | Array of producing companies |
| `runtimeMinutes` | Runtime in minutes |
| `tagline` | Marketing tagline |
| `description` | Plot summary (from og:description) |
| `originalLanguages` | Primary language(s) |
| `posterUrl` | Poster image URL |
| `averageRating` | Letterboxd average rating (0-5 scale, e.g. `4.53`) |
| `ratingsCount` | Total user ratings cast |
| `reviewsCount` | Total user reviews |

#### User records (`recordType=user`)

| Field | Description |
| --- | --- |
| `username` | Letterboxd handle |
| `url` | Profile URL |
| `displayName` | Display name |
| `bio` | Profile bio |
| `avatarUrl` | Avatar image URL |
| `filmsLogged` | Total films logged |
| `filmsThisYear` | Films logged in the current year |
| `followersCount` | Follower count |
| `followingCount` | Following count |

Empty fields are dropped from every record at every depth — the dataset never contains nulls.

### Input

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Enum | `film` | One of `film` / `search` / `userProfile` / `lists` / `popular` / `filmReviews` / `byCrew` / `userWatchlist` |
| `filmSlugs` | Array | `["parasite-2019"]` | Slugs (`parasite-2019`) or full URLs. Used when `mode=film` |
| `filmSlug` | String | — | Single film slug for `mode=filmReviews` |
| `searchQuery` | String | — | Film title query. Used when `mode=search` |
| `enrichSearchResults` | Boolean | `false` | When `mode=search`, also visit each film's page for full metadata. Slower but enables year / rating / genre filters |
| `username` | String | — | Letterboxd handle. Used when `mode=userProfile` or `mode=userWatchlist` |
| `listUrl` | String | — | Letterboxd list URL for `mode=lists` (single list). Leave empty to fetch popular lists index |
| `popularPeriod` | Enum | `week` | `week` / `month` / `year` / `all-time` — used by `mode=popular` and `mode=lists` (popular lists index) |
| `crewType` | Enum | `director` | `director` / `actor` / `studio` / `country` — used by `mode=byCrew` |
| `crewSlug` | String | — | Letterboxd slug for the crew person/entity (e.g. `christopher-nolan`, `a24`, `japan`) |
| `minYear` / `maxYear` | Integer | — | Drop films outside the year range |
| `minRating` | Integer | — | Drop films with average rating below this. Scale is `0-500` (i.e. `350` = `3.5/5`) |
| `genre` | Enum | — | Drop films missing this genre. One of 19 Letterboxd genres (Action, Adventure, Animation, Comedy, Crime, Documentary, Drama, Family, Fantasy, History, Horror, Music, Mystery, Romance, Science Fiction, TV Movie, Thriller, War, Western) |
| `maxItems` | Integer | `25` | Hard cap on emitted records (1-500) |

#### Example input — single film

```json
{
  "mode": "film",
  "filmSlugs": ["parasite-2019", "the-godfather", "dune-part-two"]
}
````

#### Example input — search by title

```json
{
  "mode": "search",
  "searchQuery": "Dune",
  "maxItems": 25
}
```

#### Example input — search with full metadata enrichment

```json
{
  "mode": "search",
  "searchQuery": "Christopher Nolan",
  "enrichSearchResults": true,
  "minYear": 2000,
  "minRating": 350,
  "maxItems": 50
}
```

#### Example input — user profile

```json
{
  "mode": "userProfile",
  "username": "dave"
}
```

#### Example input — popular films this week

```json
{
  "mode": "popular",
  "popularPeriod": "week",
  "maxItems": 50
}
```

#### Example input — list contents

```json
{
  "mode": "lists",
  "listUrl": "https://letterboxd.com/dave/list/official-top-250-narrative-feature-films/",
  "maxItems": 50
}
```

#### Example input — popular lists index

```json
{
  "mode": "lists",
  "popularPeriod": "week",
  "maxItems": 25
}
```

#### Example input — film reviews

```json
{
  "mode": "filmReviews",
  "filmSlug": "parasite-2019",
  "maxItems": 50
}
```

#### Example input — films by director / studio / country

```json
{
  "mode": "byCrew",
  "crewType": "director",
  "crewSlug": "christopher-nolan",
  "maxItems": 50
}
```

```json
{
  "mode": "byCrew",
  "crewType": "studio",
  "crewSlug": "a24",
  "maxItems": 50
}
```

```json
{
  "mode": "byCrew",
  "crewType": "country",
  "crewSlug": "japan",
  "maxItems": 100
}
```

#### Example input — user watchlist

```json
{
  "mode": "userWatchlist",
  "username": "dave",
  "maxItems": 100
}
```

### Example output

```json
{
  "recordType": "film",
  "slug": "parasite-2019",
  "url": "https://letterboxd.com/film/parasite-2019/",
  "title": "Parasite",
  "year": 2019,
  "directors": ["Bong Joon Ho"],
  "cast": ["Song Kang-ho", "Lee Sun-kyun", "Cho Yeo-jeong"],
  "genres": ["Thriller", "Comedy", "Drama"],
  "countries": ["South Korea"],
  "runtimeMinutes": 133,
  "tagline": "Act like you own the place.",
  "description": "All unemployed, Ki-taek's family takes peculiar interest in the wealthy and glamorous Parks…",
  "originalLanguages": ["Korean"],
  "averageRating": 4.53,
  "ratingsCount": 5323455,
  "reviewsCount": 700624,
  "posterUrl": "https://a.ltrbxd.com/resized/sm/upload/oi/ha/78/z8/parasite-1200-1200-675-675-crop-000000.jpg",
  "scrapedAt": "2026-05-06T05:42:18Z"
}
```

### Use cases

- **Film recommendation engines** — Pull rich metadata + community ratings for any film catalogue.
- **Entertainment research** — Track average rating and review count over time for industry analysis.
- **Content discovery** — Search Letterboxd's index and filter by year / rating / genre.
- **Competitive review analysis** — Pair with our IMDb / Rotten Tomatoes scrapers for full-spectrum film coverage.
- **CRM enrichment** — Augment cinephile lead records with public Letterboxd activity (films logged, follower counts).
- **Academic / film studies** — Snapshot community-driven ratings + tags for sociological analysis.

### FAQ

**Do I need a Letterboxd account?**
No. The Letterboxd film pages, search endpoint, and public profiles all serve anonymous traffic.

**Why Chrome 131 TLS impersonation?**
Letterboxd is fronted by a Cloudflare WAF that fingerprints the TLS handshake and rejects vanilla Python clients. Chrome 131 impersonation matches the fingerprint of a real desktop Chrome browser and passes through cleanly.

**How does search work?**
The actor uses Letterboxd's `/s/autocompletefilm?q=...` JSON endpoint, which is much richer (and more reliable) than scraping the React-rendered search page. Each result includes slug, title, release year, runtime, and director. Set `enrichSearchResults=true` to follow each result with a full film-page fetch (needed for year / rating / genre filters and to get genres, cast, ratings count).

> The autocomplete endpoint refuses unauthenticated requests from many datacenter IP ranges. The actor's input default is `proxy: {useApifyProxy: true, apifyProxyGroups: ["RESIDENTIAL"]}` which routes through residential IPs and works reliably. `mode=film` and `mode=userProfile` work without proxy too — proxy is only mandatory for `mode=search`.

**How do `minYear` / `maxYear` / `minRating` / `genre` filters interact with search?**
Filters require full film metadata to evaluate. If any filter is set in `mode=search`, the actor automatically enriches each search result with a film-page fetch (slower but accurate).

**Can I scrape reviews?**
Yes — set `mode=filmReviews` and provide a `filmSlug`. Each record has the reviewer's username + display name, the rating they gave, the review text, the review date, the like / comment counts, and the canonical review URL. Pagination is automatic up to `maxItems`.

**How do I list a director's / actor's / studio's filmography?**
Set `mode=byCrew`, choose `crewType` (`director` / `actor` / `studio` / `country`) and provide the matching `crewSlug` (Letterboxd's URL slug — e.g. `christopher-nolan`, `timothee-chalamet`, `a24`, `japan`).

**How do I scrape a list's contents?**
Set `mode=lists` and pass the full list URL in `listUrl`. The first record is the list's metadata (`recordType=list`); subsequent records are the films in the list (`recordType=film`) preserving original order via `listPosition`. Leaving `listUrl` empty returns the **popular lists index** for the chosen `popularPeriod`.

**How current is the data?**
Live — every run hits Letterboxd at request time. Schedule the actor for daily / hourly refreshes to track rating drift on a film catalogue.

**Do I need a proxy?**
No. The Cloudflare WAF accepts datacenter IPs as long as the TLS fingerprint is real (which Chrome 131 impersonation provides). The actor sets a polite User-Agent and stays well under any rate limit.

### Limitations

- `mode=search` and the listing-based modes (`popular`, `lists`, `byCrew`, `userWatchlist`) work best with Apify Residential Proxy (input default). `mode=film`, `mode=userProfile`, and `mode=filmReviews` work without proxy from most IPs.
- Letterboxd lists pages return up to 100 films per page (multiple pages auto-paginated up to `maxItems`).
- TLS fingerprints can shift; if a future Cloudflare update breaks Chrome 131 impersonation, we'll bump to the latest supported impersonation profile.
- Country `crewSlug` uses Letterboxd's slug format (e.g. `japan`, `south-korea`, `usa`), not ISO-2.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `filmSlugs` (type: `array`):

Film slugs (e.g. `parasite-2019`) or full Letterboxd URLs (`https://letterboxd.com/film/parasite-2019/`).

## `filmSlug` (type: `string`):

Single film slug or URL whose reviews to scrape (e.g. `parasite-2019`).

## `searchQuery` (type: `string`):

Film title query (e.g. `Dune`, `The Godfather`). Note: the underlying autocomplete API returns at most ~100 results per query; for deeper results use `mode=film` with explicit `filmSlugs`.

## `enrichSearchResults` (type: `boolean`):

When `mode=search`, also visit each film's page to pull full metadata (rating, genres, cast). Adds ~0.5s per result but enables year/rating/genre filters.

## `username` (type: `string`):

Letterboxd username (without @).

## `listUrl` (type: `string`):

Full Letterboxd list URL (e.g. `https://letterboxd.com/dave/list/official-top-250-narrative-feature-films/`). Leave empty to fetch the popular-lists index for the chosen `popularPeriod`.

## `popularPeriod` (type: `string`):

Time window for popularity ranking.

## `crewType` (type: `string`):

Which crew axis to browse films by.

## `crewSlug` (type: `string`):

Letterboxd slug for the chosen `crewType`. E.g. `christopher-nolan` (director), `timothee-chalamet` (actor), `a24` (studio), `japan` or `south-korea` (country).

## `minYear` (type: `integer`):

Drop films released before this year.

## `maxYear` (type: `integer`):

Drop films released after this year.

## `minRating` (type: `integer`):

Drop films with average rating (0-5 scale ×100, so 350 = 3.5/5) below this. Optional.

## `genre` (type: `string`):

Drop films missing this genre. Also used to scope `mode=popular` URL.

## `maxItems` (type: `integer`):

Hard cap on emitted records.

## `proxy` (type: `object`):

Optional Apify Proxy. Letterboxd's autocomplete endpoint (used by `mode=search`) blocks many datacenter IPs, so residential is recommended for search. `mode=film` and `mode=userProfile` work without proxy.

## Actor input object example

```json
{
  "mode": "film",
  "filmSlugs": [
    "parasite-2019"
  ],
  "filmSlug": "parasite-2019",
  "searchQuery": "Dune",
  "enrichSearchResults": false,
  "username": "dave",
  "popularPeriod": "week",
  "crewType": "director",
  "crewSlug": "christopher-nolan",
  "maxItems": 25,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped films and user profiles.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "film",
    "filmSlugs": [
        "parasite-2019"
    ],
    "filmSlug": "parasite-2019",
    "searchQuery": "Dune",
    "enrichSearchResults": false,
    "username": "dave",
    "popularPeriod": "week",
    "crewType": "director",
    "crewSlug": "christopher-nolan",
    "maxItems": 25,
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/letterboxd-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "film",
    "filmSlugs": ["parasite-2019"],
    "filmSlug": "parasite-2019",
    "searchQuery": "Dune",
    "enrichSearchResults": False,
    "username": "dave",
    "popularPeriod": "week",
    "crewType": "director",
    "crewSlug": "christopher-nolan",
    "maxItems": 25,
    "proxy": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/letterboxd-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "film",
  "filmSlugs": [
    "parasite-2019"
  ],
  "filmSlug": "parasite-2019",
  "searchQuery": "Dune",
  "enrichSearchResults": false,
  "username": "dave",
  "popularPeriod": "week",
  "crewType": "director",
  "crewSlug": "christopher-nolan",
  "maxItems": 25,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call crawlerbros/letterboxd-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/letterboxd-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Letterboxd Scraper",
        "description": "Scrape Letterboxd, the cinephile community's film database. Pull film metadata (directors, cast, genres, runtime, ratings, tagline), search by title, browse popular films, or fetch a member's profile. Pure HTTP, no login required.",
        "version": "1.0",
        "x-build-id": "6Xtgunasf5aVFWcwG"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/crawlerbros~letterboxd-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-crawlerbros-letterboxd-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/crawlerbros~letterboxd-scraper/runs": {
            "post": {
                "operationId": "runs-sync-crawlerbros-letterboxd-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/crawlerbros~letterboxd-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-crawlerbros-letterboxd-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "mode"
                ],
                "properties": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "film",
                            "search",
                            "userProfile",
                            "lists",
                            "popular",
                            "filmReviews",
                            "byCrew",
                            "userWatchlist"
                        ],
                        "type": "string",
                        "description": "What to fetch.",
                        "default": "film"
                    },
                    "filmSlugs": {
                        "title": "Film slugs / URLs (mode=film)",
                        "type": "array",
                        "description": "Film slugs (e.g. `parasite-2019`) or full Letterboxd URLs (`https://letterboxd.com/film/parasite-2019/`).",
                        "default": [
                            "parasite-2019"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "filmSlug": {
                        "title": "Film slug (mode=filmReviews)",
                        "type": "string",
                        "description": "Single film slug or URL whose reviews to scrape (e.g. `parasite-2019`)."
                    },
                    "searchQuery": {
                        "title": "Search query (mode=search)",
                        "type": "string",
                        "description": "Film title query (e.g. `Dune`, `The Godfather`). Note: the underlying autocomplete API returns at most ~100 results per query; for deeper results use `mode=film` with explicit `filmSlugs`."
                    },
                    "enrichSearchResults": {
                        "title": "Enrich search results with full film page",
                        "type": "boolean",
                        "description": "When `mode=search`, also visit each film's page to pull full metadata (rating, genres, cast). Adds ~0.5s per result but enables year/rating/genre filters.",
                        "default": false
                    },
                    "username": {
                        "title": "Username (mode=userProfile / userWatchlist)",
                        "type": "string",
                        "description": "Letterboxd username (without @)."
                    },
                    "listUrl": {
                        "title": "List URL (mode=lists)",
                        "type": "string",
                        "description": "Full Letterboxd list URL (e.g. `https://letterboxd.com/dave/list/official-top-250-narrative-feature-films/`). Leave empty to fetch the popular-lists index for the chosen `popularPeriod`."
                    },
                    "popularPeriod": {
                        "title": "Popular period (mode=popular / lists)",
                        "enum": [
                            "week",
                            "month",
                            "year",
                            "all-time"
                        ],
                        "type": "string",
                        "description": "Time window for popularity ranking.",
                        "default": "week"
                    },
                    "crewType": {
                        "title": "Crew type (mode=byCrew)",
                        "enum": [
                            "director",
                            "actor",
                            "studio",
                            "country"
                        ],
                        "type": "string",
                        "description": "Which crew axis to browse films by.",
                        "default": "director"
                    },
                    "crewSlug": {
                        "title": "Crew slug (mode=byCrew)",
                        "type": "string",
                        "description": "Letterboxd slug for the chosen `crewType`. E.g. `christopher-nolan` (director), `timothee-chalamet` (actor), `a24` (studio), `japan` or `south-korea` (country)."
                    },
                    "minYear": {
                        "title": "Min release year",
                        "minimum": 1880,
                        "maximum": 2100,
                        "type": "integer",
                        "description": "Drop films released before this year."
                    },
                    "maxYear": {
                        "title": "Max release year",
                        "minimum": 1880,
                        "maximum": 2100,
                        "type": "integer",
                        "description": "Drop films released after this year."
                    },
                    "minRating": {
                        "title": "Min average rating",
                        "minimum": 0,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Drop films with average rating (0-5 scale ×100, so 350 = 3.5/5) below this. Optional."
                    },
                    "genre": {
                        "title": "Genre filter",
                        "enum": [
                            "Action",
                            "Adventure",
                            "Animation",
                            "Comedy",
                            "Crime",
                            "Documentary",
                            "Drama",
                            "Family",
                            "Fantasy",
                            "History",
                            "Horror",
                            "Music",
                            "Mystery",
                            "Romance",
                            "Science Fiction",
                            "TV Movie",
                            "Thriller",
                            "War",
                            "Western"
                        ],
                        "type": "string",
                        "description": "Drop films missing this genre. Also used to scope `mode=popular` URL."
                    },
                    "maxItems": {
                        "title": "Max items",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Hard cap on emitted records.",
                        "default": 25
                    },
                    "proxy": {
                        "title": "Apify Proxy (optional)",
                        "type": "object",
                        "description": "Optional Apify Proxy. Letterboxd's autocomplete endpoint (used by `mode=search`) blocks many datacenter IPs, so residential is recommended for search. `mode=film` and `mode=userProfile` work without proxy.",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ]
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
