# Letterboxd Scraper — Films, Ratings, Watchlists & Lists (`hipersoft/letterboxd-scraper`) Actor

Scrape Letterboxd films with ratings, rating counts, genres, director, cast, runtime and synopsis. Feed it film pages, a user's films/watchlist/diary, any list URL, or browse pages. Clears Cloudflare. For film data, recommendations and research.

- **URL**: https://apify.com/hipersoft/letterboxd-scraper.md
- **Developed by:** [hiper soft](https://apify.com/hipersoft) (community)
- **Categories:** Videos, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.003 / film scraped

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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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, Ratings, Watchlists & Lists

Extract rich film data from **Letterboxd** — **average rating, number of ratings, genres, director, cast, runtime, synopsis, countries, languages and poster** — into clean JSON, CSV or Excel. Point it at **individual films**, a **user's films / watchlist / diary**, any **list**, or a **browse page** (popular, by rating, by genre). Automatically handles bot protection.

Great for **film datasets, recommendation engines, ranking & analytics, watchlist backups and research**.

### What you can scrape

- 🎬 **Single films** — `letterboxd.com/film/parasite-2019/`
- 👤 **A user's films, watchlist or diary** — `letterboxd.com/USERNAME/watchlist/`
- 📋 **Any list** — `letterboxd.com/USERNAME/list/LIST-NAME/`
- 🔥 **Browse pages** — popular this week, by rating, by genre, by decade…

Give it any mix of these as **Start URLs** — it walks the poster grid, follows pagination, and pulls full metadata for every film it finds.

### Example input

```json
{
  "startUrls": [
    "https://letterboxd.com/films/popular/this/week/",
    "https://letterboxd.com/dave/watchlist/",
    "https://letterboxd.com/film/parasite-2019/"
  ],
  "maxFilms": 200,
  "maxListPages": 20
}
```

### Output

One row per film:

```json
{
  "title": "Parasite",
  "year": 2019,
  "rating": 4.52,
  "ratingCount": 5635651,
  "director": ["Bong Joon Ho"],
  "genres": ["Thriller", "Comedy", "Drama"],
  "runtimeMinutes": 133,
  "cast": ["Song Kang-ho", "Lee Sun-kyun", "Cho Yeo-jeong", "…"],
  "countries": ["South Korea"],
  "languages": ["Korean", "English"],
  "synopsis": "…",
  "poster": "https://a.ltrbxd.com/resized/film-poster/…jpg",
  "imdbUrl": "https://www.imdb.com/title/tt6751668/",
  "tmdbUrl": "https://www.themoviedb.org/movie/496243",
  "url": "https://letterboxd.com/film/parasite-2019/"
}
```

### Input fields

| Field | Description |
|-------|-------------|
| `startUrls` | Film pages, user pages (watchlist/films/diary), list URLs or browse pages. Bare film slugs also work. |
| `maxFilms` | Max films to scrape in total across all start URLs. |
| `maxListPages` | For listing URLs, how many paginated pages to walk. |
| `proxyConfiguration` | Residential proxy (for reliable access) — leave default. |

### Use cases

- **Build a film dataset** — ratings, genres and crew for thousands of titles
- **Recommendation & ranking** — use real Letterboxd ratings and rating counts as signal
- **Watchlist / diary backup** — export a user's watched films or watchlist to a spreadsheet
- **Genre & decade analysis** — scrape a browse page and crunch the numbers
- **Enrich your movie app** — pull posters, runtime, cast and synopsis by URL

### FAQ

**Does it handle bot protection?**
Yes. Letterboxd's browse, user and list pages sit behind a bot protection challenge; this Actor handles bot protection automatically, retrying if needed.

**How many films can I scrape?**
Set `maxFilms` up to 100,000. For listing URLs it pages through the poster grid automatically.

**Can I scrape a specific user's watchlist or diary?**
Yes — use their `watchlist/`, `films/` or `films/diary/` URL as a start URL.

**How does billing work?**
Pay per film scraped — you only pay for the films you actually get.

**Is a login needed?**
No. Only public Letterboxd pages are scraped.

### Related Actors

- [IMDb-style data via TVmaze Scraper](https://apify.com/hipersoft/tvmaze-scraper) — TV shows, episodes and cast
- [Steam Games Scraper](https://apify.com/hipersoft/steam-games-scraper) — game catalog, prices and reviews
- [Google Trends Scraper](https://apify.com/hipersoft/google-trends-scraper) — interest over time for any title

### Notes

Original clean-room implementation. Scrapes only public Letterboxd pages; you are responsible for how you use the data and for complying with Letterboxd's terms. This is an independent tool and is not affiliated with or endorsed by Letterboxd.

# Actor input Schema

## `startUrls` (type: `array`):

Letterboxd URLs to scrape. Each can be a film page (letterboxd.com/film/parasite-2019/), a user's films/watchlist/diary (letterboxd.com/USER/watchlist/), a list (letterboxd.com/USER/list/NAME/), or a browse page (letterboxd.com/films/popular/this/week/). Bare film slugs also work.

## `maxFilms` (type: `integer`):

Maximum number of films to scrape in total across all start URLs.

## `maxListPages` (type: `integer`):

For listing/user/browse URLs, how many paginated pages to walk collecting films.

## `proxyConfiguration` (type: `object`):

Proxy settings. Residential is required to clear Cloudflare; leave default.

## Actor input object example

```json
{
  "startUrls": [
    "https://letterboxd.com/dave/watchlist/",
    "https://letterboxd.com/film/parasite-2019/"
  ],
  "maxFilms": 100,
  "maxListPages": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "startUrls": [
        "https://letterboxd.com/films/popular/this/week/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("hipersoft/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 = { "startUrls": ["https://letterboxd.com/films/popular/this/week/"] }

# Run the Actor and wait for it to finish
run = client.actor("hipersoft/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 '{
  "startUrls": [
    "https://letterboxd.com/films/popular/this/week/"
  ]
}' |
apify call hipersoft/letterboxd-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/nS4IzBxzjLCC9dQnN/builds/VkJXZ1DF5e77N1GqL/openapi.json