# Letterboxd Scraper β€” Films, Reviews, Ratings & Lists (`tortuga/letterboxd-scraper`) Actor Scrape Letterboxd films and reviews: average rating, rating histogram, genres, cast and crew, plus reviews with star rating, full text, dates and likes. From film URLs, slugs, lists or browse pages. - **URL**: https://apify.com/tortuga/letterboxd-scraper.md - **Developed by:** [Trevor Ortega](https://apify.com/tortuga) (community) - **Categories:** Videos - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 reviews 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/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Letterboxd Scraper Scrape Letterboxd films and reviews: average rating, rating histogram, genres, cast and crew, plus member reviews with star rating, text, date and likes. Works with film URLs, slugs, lists and popular pages. Letterboxd Scraper turns any Letterboxd film into clean JSON. In `reviews` mode you get every review as its own row, with the half-star rating, the **full** review text (long reviews are expanded automatically), the watched or published date, likes, comments, rewatch and spoiler flags and the review language. You can sort the same way the website does (popular, newest, oldest, highest or lowest rated) or keep only one star rating. Letterboxd shows at most 3,072 reviews per sort order. When a film has more, the actor carries on through each star-rating bucket, so big titles yield up to about 30,000 reviews. In `films` mode you get the average rating with the full 0.5-5 star histogram, ratings/reviews/watched/likes/lists/fans counts, the Letterboxd Top 500 rank, directors, top-billed cast with characters, the full crew by role, genres, themes, countries, languages, studios, runtime, tagline, synopsis, poster and backdrop, IMDb and TMDB ids and every release date per country with its certification. Lists, browse pages (popular this week, any genre, decade, year...) and film search are covered too. No Letterboxd account is needed. Download JSON, CSV or Excel, or use the API from Python, Node, n8n, Make or Google Sheets. You pay only for the items you get: **$1 per 1,000 reviews**. ### What data does Letterboxd Scraper extract? Every item has a `type` field: `review`, `film` or `list_entry`. #### Review items (`type: "review"`, mode `reviews`) | Field | Description | |---|---| | `filmSlug`, `filmTitle`, `filmYear`, `filmId` | The film the review belongs to | | `reviewId`, `url` | Letterboxd's numeric review (viewing) id and its `boxd.it` short link | | `rating` | 0.5-5 in half stars, or `null` when the reviewer gave no rating | | `text`, `textHtml` | Full review text as plain text and as HTML (truncated reviews are expanded) | | `isTextTruncated` | `true` only if the full text could not be loaded or `fetchFullReviewText` is off | | `language` | Language code of the review text, e.g. `en`, `pt`, `ar` | | `watchedDate` | Diary date (`YYYY-MM-DD`) when the review is a diary entry | | `publishedAt` | When the review was posted (ISO 8601). Always set for reviews without a diary date; for diary entries turn on `fetchReviewPublishDates` | | `likesCount`, `commentsCount` | Likes and comments on the review | | `isLiked` | Whether the reviewer also "liked" (hearted) the film | | `isRewatch` | Whether the review is for a rewatch | | `containsSpoilers` | Whether the review is marked as containing spoilers | | `authorName` | Reviewer's display name as shown on the review ("Philbert Dy") | | `authorUsername` | Reviewer's Letterboxd username (handle), as in their profile URL (`philbertdy`) | | `authorUrl` | Reviewer's public profile page (`https://letterboxd.com/philbertdy/`) | | `scrapedAt` | ISO 8601 timestamp | Reviewer avatars are not collected. Letterboxd shows no numeric member id on reviews, so there is no `authorId` field. #### Film items (`type: "film"`, mode `films`) | Field | Description | |---|---| | `id`, `slug`, `url`, `shortUrl` | Letterboxd film id, slug, page URL and `boxd.it` link | | `title`, `originalTitle`, `alternativeTitles`, `year` | Titles and release year | | `directors`, `cast`, `crew` | `[{name, url}]`; cast `[{name, character, url}]` in billing order; crew `{"Writers": [...], "Composer": [...], ...}` | | `genres`, `themes` | Genres and Letterboxd themes/mini-themes | | `countries`, `languages`, `primaryLanguage`, `studios` | Production details | | `runtimeMinutes`, `tagline`, `description` | Runtime, tagline and synopsis | | `averageRating`, `ratingsCount`, `reviewsCount` | Weighted average (0.5-5), number of ratings and reviews | | `ratingHistogram` | `{"0.5": n, "1": n, ..., "5": n}` rating counts | | `watchedCount`, `likesCount`, `listsCount`, `fansCount`, `top500Rank` | Member stats (exact counts) and the rank in Letterboxd's Top 500 | | `posterUrl`, `backdropUrl` | Poster (600x900) and backdrop (1920x1080) images | | `tmdbId`, `tmdbType`, `imdbId` | External ids | | `releaseDates` | `[{type, date, country, certification, note}]`, e.g. Premiere / Theatrical / Digital / Physical / TV per country | | `scrapedAt` | ISO 8601 timestamp | #### List, browse and search rows (`type: "list_entry"`, modes `list` and `browse`) `listType` (`list`, `browse` or `search`), `listTitle`, `listUrl` (only for official Letterboxd lists, browse pages and searches; it is left out for lists made by members because their URL contains the member's username), `position`, `slug`, `title`, `year`, `url`, `filmId`, `averageRating` (browse pages only), `scrapedAt`. ### How to use Letterboxd Scraper 1. Pick a **Mode**: `reviews` (default), `films`, `list` or `browse`. 2. Add films as **Start URLs** (`https://letterboxd.com/film/parasite-2019/`), **Film slugs** (`parasite-2019`) or **Search terms** (`parasite 2019`). In `films` and `reviews` mode a list, browse or search URL expands to its first films (**Max films per list**). 3. Set **Max items** and, in `reviews` mode, **Max reviews per film**. 4. Optionally choose a **Review order** and a **star rating** filter. 5. Click **Start**. Results appear in the **Dataset** tab; export from there or use the API. ### Input example ```json { "mode": "reviews", "filmSlugs": ["parasite-2019", "the-godfather"], "maxReviewsPerFilm": 5000, "maxItems": 10000, "reviewSort": "added" } ``` ```json { "mode": "films", "startUrls": [{ "url": "https://letterboxd.com/films/popular/this/week/" }], "maxFilmsPerListing": 50, "maxItems": 50 } ``` ```json { "mode": "list", "startUrls": [{ "url": "https://letterboxd.com/official/list/letterboxds-top-500-films/" }], "maxItems": 500 } ``` ```json { "mode": "browse", "startUrls": [{ "url": "https://letterboxd.com/films/genre/horror/" }, { "url": "https://letterboxd.com/films/decade/1990s/" }], "maxItems": 300 } ``` ### Output example ```json { "type": "review", "filmSlug": "parasite-2019", "filmTitle": "Parasite", "filmYear": 2019, "filmId": 426406, "reviewId": 72286970, "url": "https://boxd.it/MV5qJ", "rating": 5.0, "isLiked": true, "text": "Update: Now in video form\n\nThere is a house on a hill, and there are people in it. And they're nice, but not really. ...", "textHtml": "

Update: Now in video form

There is a house on a hill ...

", "isTextTruncated": false, "language": "en", "watchedDate": "2019-08-14", "publishedAt": null, "likesCount": 44548, "commentsCount": 248, "isRewatch": false, "containsSpoilers": true, "authorName": "Philbert Dy", "authorUsername": "philbertdy", "authorUrl": "https://letterboxd.com/philbertdy/", "scrapedAt": "2026-10-05T17:03:16Z" } ``` ```json { "type": "film", "id": 426406, "slug": "parasite-2019", "url": "https://letterboxd.com/film/parasite-2019/", "shortUrl": "https://boxd.it/hTha", "title": "Parasite", "originalTitle": "기생좩", "year": 2019, "directors": [{ "name": "Bong Joon Ho", "url": "https://letterboxd.com/director/bong-joon-ho/" }], "cast": [{ "name": "Song Kang-ho", "character": "Kim Ki-taek", "url": "https://letterboxd.com/actor/song-kang-ho/" }], "crew": { "Writers": ["Kim Dae-hwan", "Bong Joon Ho", "Han Jin-won"], "Composer": ["Jung Jae-il"] }, "genres": ["Thriller", "Comedy", "Drama"], "themes": ["Intense violence and sexual transgression", "Humanity and the world around us"], "countries": ["South Korea"], "languages": ["Korean", "English", "German"], "studios": ["Barunson E&A"], "runtimeMinutes": 133, "averageRating": 4.52, "ratingsCount": 5904509, "ratingHistogram": { "0.5": 5624, "1": 13987, "1.5": 6569, "2": 42344, "2.5": 37615, "3": 241316, "3.5": 284194, "4": 1321126, "4.5": 1025236, "5": 2926500 }, "reviewsCount": 794155, "watchedCount": 7634477, "likesCount": 3927747, "listsCount": 898946, "fansCount": 196844, "top500Rank": 16, "tagline": "Act like you own the place.", "posterUrl": "https://a.ltrbxd.com/resized/film-poster/4/2/6/4/0/6/426406-parasite-0-600-0-900-crop.jpg?v=8f5653f710", "tmdbId": 496243, "imdbId": "tt6751668", "releaseDates": [{ "type": "Premiere", "date": "2019-05-21", "country": "France", "certification": null, "note": "Cannes Film Festival" }] } ``` ### How to scrape all Letterboxd reviews of a film Use `reviews` mode with the film URL or slug and set **Max reviews per film** high. Reviews are read 12 per page, the same pages the website shows. Letterboxd stops every sort order at page 256 (3,072 reviews), so for bigger films the actor continues with the 5-star, 4.5-star, ... and unrated buckets and drops duplicates. That way a film with hundreds of thousands of reviews still gives up to about 30,000 unique reviews. Only reviews whose text is shortened on the listing cost an extra small request (typically 1-2 per 24 reviews). ### Can I get only negative (or positive) reviews? Yes. Set **Only reviews with this rating** to a value from `0.5` to `5`, or `none` for unrated reviews. You can also paste a filtered reviews URL from the website, such as `https://letterboxd.com/film/parasite-2019/reviews/rated/1/by/added/`, and the actor keeps that filter and order. ### How to scrape Letterboxd popular films, genres and lists Use `browse` mode with any `/films/...` page: `/films/popular/this/week/`, `/films/genre/horror/`, `/films/decade/1990s/`, `/films/year/2024/` and so on (72 films per page, in the page's order). Use `list` mode with an official list such as `/official/list/letterboxds-top-500-films/` or any member list (100 films per page). Switch to `films` mode with the same URLs to get the full film item for each film. ### Monitor changes on a schedule Turn on **Only new or changed items** and save the input as a task with a Schedule (Apify Console: **Saved tasks** -> **Schedule**, for example daily). Each run then remembers what earlier runs of the same input returned and outputs only what is new: new reviews in `reviews` mode (read newest first; full texts are loaded only for new reviews), films whose average rating or Top 500 rank changed in `films` mode, and new list or browse rows or rows whose average rating changed. Unchanged items are skipped before they are saved, so they are not charged. Add **Only reviews newer than** (`7 days`, `24 hours` or a date like `2026-10-01`) to limit the first run to recent reviews; paging stops as soon as a page reaches older or already-seen reviews. Monitored items carry `changeType` (`new` or `changed`) and, for changed films and rows, `previousValues` with the old values of the fields that changed (e.g. `{"averageRating": 4.52}`); **Monitoring key** keeps several schedules on the same input apart. ### Does it work without a Letterboxd account? Yes. The actor only reads pages Letterboxd serves to logged-out visitors over plain HTTP: no login, account cookies or browser. It never reads private data, diaries or profiles. ### Which proxy should I use? Keep the default (Apify Proxy). Letterboxd's Cloudflare protection challenges Apify datacenter IPs on deeper pages (review pages 2+, full review texts, rating fragments) at times. The actor then retries the request through Apify's residential proxy automatically and, once that has happened twice in a run, uses residential IPs for the rest of the run. Residential traffic is billed by Apify per GB on your account: a review page is about 30 KB on the wire, so it adds roughly $0.00003 per review. The run summary (`SUMMARY` in the key-value store) reports `residentialFallbacks` and `okByProxy`. If your plan has no residential proxy, the actor stays on datacenter IPs and retries more. ### Is scraping Letterboxd legal? This actor collects only data Letterboxd shows publicly to logged-out visitors: film metadata, aggregate statistics, public review texts with the reviewer's display name, username and public profile link as shown next to the review, and public lists. It does not collect avatars, does not scrape member profiles, diaries or watchlists, and reads nothing behind a login. Reviewer names, usernames and profile links are personal data under GDPR and similar laws: make sure you have a lawful basis for processing them, and do not use them to contact or profile individuals. You are responsible for how you use the data and for following Letterboxd's terms and applicable law (GDPR/CCPA). ### Pricing Pay per item: `review` $0.001, `film` $0.003, list/browse/search row $0.001. There is no start fee and no subscription. 10,000 reviews cost $10. ### Integrations and API Use the run in Zapier, Make, n8n, Google Sheets, or call it from Python/Node with the Apify client. See the **API** tab for ready-made snippets. See also: [Goodreads Scraper](https://apify.com/tortuga/goodreads-scraper) for book ratings and reviews. ### Support Found a bug or need a field added? Open an issue in the **Issues** tab; it is usually answered within a day. # Actor input Schema ## `mode` (type: `string`): What to scrape. `reviews`: `review` items for each film (star rating, full text, dates, likes, comments). `films`: one `film` item per film (ratings, rating histogram, cast, crew, genres, themes, release dates, stats). `list`: `list_entry` rows from Letterboxd lists. `browse`: `list_entry` rows from browse pages such as popular this week, a genre or a decade. In `films`/`reviews` mode, list and browse URLs are expanded into their first films (see `maxFilmsPerListing`). ## `startUrls` (type: `array`): Letterboxd URLs, one per line: films (`/film/parasite-2019/`), film reviews with any order or rating filter (`/film/parasite-2019/reviews/by/added/`, `/film/parasite-2019/reviews/rated/5/by/activity/`), lists (`/official/list/letterboxds-top-500-films/`, `//list//`) or browse pages (`/films/popular/this/week/`, `/films/genre/horror/`, `/films/decade/1990s/`). ## `filmSlugs` (type: `array`): Letterboxd film slugs (the part after `/film/` in the URL), one per line, e.g. `parasite-2019`, `the-godfather`, `everything-everywhere-all-at-once`. ## `searchTerms` (type: `array`): Film titles, one per line (add the year for remakes, e.g. `dune 2021`). In `films`/`reviews` mode each term resolves to its best match from Letterboxd's film search; in `list`/`browse` mode the search results themselves are returned as rows. ## `maxItems` (type: `integer`): Overall cap on dataset items for the run (all item types combined). Keeps cost predictable. ## `maxReviewsPerFilm` (type: `integer`): Cap on reviews collected for each film in `reviews` mode. Letterboxd shows at most 3,072 reviews per sort order; above that the actor continues through each star-rating bucket, so popular films can yield up to about 30,000 reviews. ## `reviewSort` (type: `string`): Order of reviews, same as the website: `activity` = popular (most liked and discussed), `added` = newest, `added-earliest` = oldest, `entry-rating` = highest rated, `entry-rating-lowest` = lowest rated. A reviews URL in Start URLs keeps its own order. ## `reviewRating` (type: `string`): Keep only reviews with this star rating (`0.5` to `5` in half stars) or `none` for reviews without a rating. Leave empty for all. ## `fetchFullReviewText` (type: `boolean`): Long reviews are shortened on Letterboxd's review pages. When on, the full text is loaded for those reviews only (one small extra request each; most reviews are short and need none). ## `fetchReviewPublishDates` (type: `boolean`): Reviews logged with a diary date show the watched date on listing pages; their publish date is only on the review's own page. When on, that page is loaded for each such review (one extra request per review, slower). Reviews without a diary date always get `publishedAt` for free. ## `maxFilmsPerListing` (type: `integer`): In `films` and `reviews` mode, how many films to take from each list, browse or search URL before scraping their details or reviews. ## `reviewsNewerThan` (type: `string`): Only reviews posted on or after: a date (YYYY-MM-DD) or a period such as '7 days' or '24 hours'. Reviews are then read newest first (`reviewSort` becomes `added`) and paging stops at the first page that ends with an older review. Letterboxd lists diary reviews with the watched date only; the actor places them by their position in the newest-first list and fetches the publish date (one small extra request) only for the few reviews near the cutoff that their neighbours cannot place. Leave empty for no date limit. `reviews` mode only. ## `onlyNewOrChanged` (type: `boolean`): Remember what earlier runs of this input returned and output only new items: new reviews in `reviews` mode (read newest first; paging stops where the previous run's reviews begin, and full texts are loaded for new reviews only), films whose average rating or Top 500 rank changed in `films` mode, list or browse rows that are new or whose average rating changed in `list` and `browse` mode (there **Max items** caps how many rows are checked, so every run watches the same top of the list). Use with a Schedule; unchanged items are not charged. ## `monitoringKey` (type: `string`): Name for this watch, so several schedules on the same search stay separate; defaults to a key derived from the search input. Only used with **Only new or changed items**. ## `proxyConfiguration` (type: `object`): Apify Proxy is recommended. Cloudflare challenges Apify datacenter IPs on review pages 2+ and full review texts at times; the actor then retries through Apify residential proxy automatically (about 30 KB per page, billed per GB by Apify, roughly $0.00003 per review). Choose RESIDENTIAL to use it from the start. ## Actor input object example ```json { "mode": "reviews", "startUrls": [ { "url": "https://letterboxd.com/film/parasite-2019/" } ], "filmSlugs": [], "searchTerms": [], "maxItems": 100, "maxReviewsPerFilm": 100, "reviewSort": "activity", "fetchFullReviewText": true, "fetchReviewPublishDates": false, "maxFilmsPerListing": 20, "onlyNewOrChanged": false, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://letterboxd.com/film/parasite-2019/" } ], "filmSlugs": [], "searchTerms": [], "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("tortuga/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://letterboxd.com/film/parasite-2019/" }], "filmSlugs": [], "searchTerms": [], "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("tortuga/letterboxd-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).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": [ { "url": "https://letterboxd.com/film/parasite-2019/" } ], "filmSlugs": [], "searchTerms": [], "proxyConfiguration": { "useApifyProxy": true } }' | apify call tortuga/letterboxd-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,tortuga/letterboxd-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/AYJCBO6N1WxizNfvG/builds/2u1opjbsvIatGrqj8/openapi.json