# Letterboxd Scraper - Films, Reviews, Profiles & Lists (`zhorex/letterboxd-scraper`) Actor

Scrape Letterboxd films, reviews, user profiles, and popular/trending lists. Extract ratings, cast, crew, review text, and watchlists. 4 modes in one actor. No API key, no proxy, no browser needed. Built for film researchers, content creators, and recommendation engines.

- **URL**: https://apify.com/zhorex/letterboxd-scraper.md
- **Developed by:** [Sami](https://apify.com/zhorex) (community)
- **Categories:** Social media, News, Other
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 item scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 - Films, Reviews, Profiles & Lists

The original Letterboxd scraper on Apify was deprecated. This is its replacement — faster, more complete, and actively maintained.

Scrape **film details**, **user reviews**, **public profiles**, and **popular/trending films** from [Letterboxd](https://letterboxd.com), the social network for film lovers with 15M+ members. No proxy needed — lightweight HTTP-only scraper.

### What can this scraper do?

#### Mode 1: Film Details (`film_details`)

Extract complete metadata for any film on Letterboxd.

**Input example:**
```json
{
    "mode": "film_details",
    "urls": [
        "https://letterboxd.com/film/parasite-2019/",
        "https://letterboxd.com/film/everything-everywhere-all-at-once/",
        "the-godfather"
    ]
}
````

**Output per film:**

```json
{
    "filmUrl": "https://letterboxd.com/film/parasite-2019/",
    "title": "Parasite",
    "year": 2019,
    "director": ["Bong Joon-ho"],
    "cast": ["Song Kang-ho", "Lee Sun-kyun", "Cho Yeo-jeong"],
    "genres": ["Comedy", "Drama", "Thriller"],
    "countries": ["South Korea"],
    "languages": ["Korean"],
    "runtime": 132,
    "averageRating": 4.6,
    "totalRatings": 1250000,
    "totalReviews": 85000,
    "totalLists": 120000,
    "posterUrl": "https://...",
    "tagline": "Act like you own the place.",
    "description": "All unemployed, Ki-taek's family...",
    "studios": ["Barunson E&A"],
    "scrapedAt": "2026-04-09T15:00:00Z"
}
```

#### Mode 2: Film Reviews (`film_reviews`)

Extract reviews for any film with sorting and pagination.

**Input example:**

```json
{
    "mode": "film_reviews",
    "urls": ["https://letterboxd.com/film/parasite-2019/"],
    "maxResults": 100,
    "sortBy": "popular"
}
```

**Output per review:**

```json
{
    "filmTitle": "Parasite",
    "filmUrl": "https://letterboxd.com/film/parasite-2019/",
    "reviewerUsername": "john_doe",
    "reviewerDisplayName": "John",
    "reviewerUrl": "https://letterboxd.com/john_doe/",
    "rating": 4.5,
    "reviewText": "A masterclass in social commentary...",
    "reviewDate": "2026-03-15",
    "reviewUrl": "https://letterboxd.com/john_doe/film/parasite-2019/",
    "likes": 42,
    "isContainsSpoilers": false,
    "scrapedAt": "2026-04-09T15:00:00Z"
}
```

**Sort options:** `popular` (default), `recent`, `earliest`, `highest`, `lowest`

#### Mode 3: User Profile (`user_profile`)

Extract public profile information including stats, favorites, and recent activity.

**Input example:**

```json
{
    "mode": "user_profile",
    "urls": ["dave", "https://letterboxd.com/sally/"]
}
```

**Output per user:**

```json
{
    "username": "dave",
    "displayName": "Dave",
    "profileUrl": "https://letterboxd.com/dave/",
    "avatarUrl": "https://...",
    "bio": "Film lover from NYC",
    "location": "New York",
    "filmsWatched": 1250,
    "filmsThisYear": 87,
    "listsCount": 15,
    "followingCount": 200,
    "followersCount": 150,
    "favoriteFilms": [
        {"title": "Parasite", "url": "https://letterboxd.com/film/parasite-2019/"}
    ],
    "recentRatings": [
        {"title": "Dune: Part Two", "rating": 4.0, "url": "https://letterboxd.com/film/dune-part-two/"}
    ],
    "scrapedAt": "2026-04-09T15:00:00Z"
}
```

#### Mode 4: Popular Films (`popular_films`)

Scrape trending and popular films with optional genre filtering.

**Input example:**

```json
{
    "mode": "popular_films",
    "category": "this-week",
    "genre": "horror",
    "maxResults": 100
}
```

**Output per film:**

```json
{
    "title": "Nosferatu",
    "year": 2024,
    "url": "https://letterboxd.com/film/nosferatu-2024/",
    "posterUrl": "https://...",
    "averageRating": 3.8,
    "director": null,
    "scrapedAt": "2026-04-09T15:00:00Z"
}
```

**Categories:** `popular`, `this-week`, `this-month`, `this-year`

### URL Flexibility

You don't need to provide full URLs. The scraper accepts:

| Input | Interpreted as |
|---|---|
| `https://letterboxd.com/film/parasite-2019/` | Film URL (used directly) |
| `letterboxd.com/film/parasite-2019` | Film URL (https:// added) |
| `parasite-2019` | Film slug (full URL constructed) |
| `https://letterboxd.com/dave/` | User profile URL |
| `dave` | Username (full URL constructed) |

### Use Cases

- **Film industry research** — Analyze ratings and review trends across thousands of films
- **Content creator analytics** — Track film popularity and audience reception over time
- **Academic research** — Study film criticism patterns, audience behavior, and cultural trends
- **Recommendation engines** — Build datasets for ML-based movie recommendation systems
- **Entertainment journalism** — Monitor trending films and critical reception in real time

### Pricing

**$0.001 per result** — the most affordable film data scraper on Apify.

| Mode | Charged per |
|---|---|
| `film_details` | Film scraped |
| `film_reviews` | Review scraped |
| `user_profile` | Profile scraped |
| `popular_films` | Film listed |

### Technical Details

- **No proxy needed** — Letterboxd is server-rendered HTML with no anti-bot measures
- **Lightweight** — HTTP-only requests, no headless browser, 256MB RAM is sufficient
- **Respectful** — Built-in 1.5s delay between requests
- **Resilient** — Automatic retry with exponential backoff on rate limits (429)
- **Fast** — Processes ~40 items/minute with built-in delays

### FAQ

**Does this need a proxy?**
No. Letterboxd serves plain HTML with no significant anti-bot protection. The built-in request delays keep the scraper well within acceptable limits.

**Can it scrape private profiles?**
No. Only publicly visible profile data is scraped. Private profiles are skipped with a warning.

**What's the rate limit?**
The scraper has a built-in 1.5-second delay between requests to be respectful to Letterboxd's servers. If rate-limited (HTTP 429), it backs off exponentially.

**Can I get full watch history?**
Only what's publicly visible on the user's profile page. The scraper does not authenticate or access private data.

**What if a film page has changed its layout?**
The scraper uses multiple fallback CSS selectors. If a field can't be parsed, it returns `null` instead of crashing.

### Other Scrapers by Zhorex

- [Telegram Channel Scraper](https://apify.com/zhorex/telegram-channel-scraper) — Scrape messages, media, and metadata from public Telegram channels
- [RedNote Xiaohongshu Scraper All-in-One](https://apify.com/zhorex/rednote-scraper) — Scrape posts, comments, and profiles from Xiaohongshu
- [G2 Reviews Scraper](https://apify.com/zhorex/g2-reviews-scraper) — Extract software reviews and ratings from G2.com
- [Domain Authority Checker](https://apify.com/zhorex/domain-authority-checker) — Bulk check domain authority for SEO analysis
- [Phone Number Validator](https://apify.com/zhorex/phone-number-validator) — Validate and format international phone numbers

### Legal

This actor only accesses publicly available data on letterboxd.com. It does not bypass any authentication, access private profiles, or circumvent technical protection measures. Use responsibly and in compliance with Letterboxd's Terms of Service.

# Actor input Schema

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

What to scrape from Letterboxd

## `urls` (type: `array`):

Film URLs for film\_details/film\_reviews, or username/profile URLs for user\_profile. Not needed for popular\_films.

## `maxResults` (type: `integer`):

Maximum reviews per film (film\_reviews mode) or max films (popular\_films mode)

## `category` (type: `string`):

Which popular films category to scrape

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

Filter by genre slug: action, comedy, drama, horror, thriller, sci-fi, animation, romance, documentary, mystery, fantasy, adventure, crime, family, history, music, war, western

## `sortBy` (type: `string`):

How to sort reviews (film\_reviews mode only)

## Actor input object example

```json
{
  "mode": "film_details",
  "urls": [
    "https://letterboxd.com/film/parasite-2019/"
  ],
  "maxResults": 50,
  "category": "popular",
  "sortBy": "popular"
}
```

# 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 = {
    "urls": [
        "https://letterboxd.com/film/parasite-2019/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zhorex/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 = { "urls": ["https://letterboxd.com/film/parasite-2019/"] }

# Run the Actor and wait for it to finish
run = client.actor("zhorex/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 '{
  "urls": [
    "https://letterboxd.com/film/parasite-2019/"
  ]
}' |
apify call zhorex/letterboxd-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Letterboxd Scraper - Films, Reviews, Profiles & Lists",
        "description": "Scrape Letterboxd films, reviews, user profiles, and popular/trending lists. Extract ratings, cast, crew, review text, and watchlists. 4 modes in one actor. No API key, no proxy, no browser needed. Built for film researchers, content creators, and recommendation engines.",
        "version": "1.0",
        "x-build-id": "pfcSUAJx63KMljHlB"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/zhorex~letterboxd-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-zhorex-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/zhorex~letterboxd-scraper/runs": {
            "post": {
                "operationId": "runs-sync-zhorex-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/zhorex~letterboxd-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-zhorex-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": "Scraping mode",
                        "enum": [
                            "film_details",
                            "film_reviews",
                            "user_profile",
                            "popular_films"
                        ],
                        "type": "string",
                        "description": "What to scrape from Letterboxd",
                        "default": "film_details"
                    },
                    "urls": {
                        "title": "URLs or identifiers",
                        "type": "array",
                        "description": "Film URLs for film_details/film_reviews, or username/profile URLs for user_profile. Not needed for popular_films.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "Max results per URL",
                        "minimum": 1,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Maximum reviews per film (film_reviews mode) or max films (popular_films mode)",
                        "default": 50
                    },
                    "category": {
                        "title": "Category (popular_films mode only)",
                        "enum": [
                            "popular",
                            "this-week",
                            "this-month",
                            "this-year"
                        ],
                        "type": "string",
                        "description": "Which popular films category to scrape",
                        "default": "popular"
                    },
                    "genre": {
                        "title": "Genre filter (optional)",
                        "type": "string",
                        "description": "Filter by genre slug: action, comedy, drama, horror, thriller, sci-fi, animation, romance, documentary, mystery, fantasy, adventure, crime, family, history, music, war, western"
                    },
                    "sortBy": {
                        "title": "Sort reviews by",
                        "enum": [
                            "popular",
                            "recent",
                            "earliest",
                            "highest",
                            "lowest"
                        ],
                        "type": "string",
                        "description": "How to sort reviews (film_reviews mode only)",
                        "default": "popular"
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```