# Letterboxd Film & Reviews Scraper (`maximedupre/letterboxd`) Actor Collect public Letterboxd film metadata, ratings, and optional reviews, or read public profiles, watched films, and lists. Choose a source, save structured rows, and export the data from your Apify dataset. - **URL**: https://apify.com/maximedupre/letterboxd.md - **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community) - **Categories:** Developer tools, Automation, Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.70 / 1,000 films 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? 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 ### 🎬 Turn Letterboxd pages into film data Film researchers, catalog teams, and developers can use this Actor to collect public Letterboxd films, ratings, reviews, profiles, watched films, and list entries in structured dataset rows. Choose a public source and get fields such as film identity, cast, genres, ratings, review text, profile activity, or list position for research and catalog work. - Check a public viewing profile with [**Letterboxd Stats**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-stats). - Find films by title or related terms with [**Letterboxd Search**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-search). - Collect public reviews for a film with [**Letterboxd Review Scraper**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-review-scraper). - Export a member's watched films with [**Letterboxd Watched Films**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-watched-films). - Read a public list with [**Letterboxd List Scraper**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-list-scraper). - Inspect a public member page with [**Letterboxd Profile Scraper**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-profile-scraper). - Browse popular films with [**Letterboxd Popular Films**](https://apify.com/maximedupre/letterboxd/examples/letterboxd-popular-films). #### 📦 Letterboxd film and activity rows **Returned data** Each dataset row has a `resultType` value. The five row shapes are `film`, `review`, `profile`, `watchedFilm`, and `listEntry`. Reviews are saved as their own rows when you include them and public reviews are available. Optional source fields can be absent when Letterboxd does not show them. #### ▶️ Choose a Letterboxd source **How to run** 1. Select a `target`: `films`, `search`, `list`, `popular`, `profile`, or `watched`. 2. Enter the URL, ID, search text, or profile name that matches the target. 3. Turn on `includeReviews` for film, search, list, or popular targets when you also want public review rows. 4. Choose a review order and turn on `completeReviewText` when you want the full text available from the source. 5. Set `maxItems` when you want an optional stop point. Leave it empty to collect all available results until the source is exhausted. 6. Start the run and open the dataset from the Output tab. Run each different film search separately. This Actor reads public Letterboxd pages and does not change ratings, lists, profiles, or other Letterboxd content. #### ⚙️ Input **Input fields** | Field | Type | What it does | | --- | --- | --- | | `target` | string | Selects `films`, `search`, `list`, `popular`, `profile`, or `watched`. | | `filmUrlsOrIds` | array of strings | Public film URLs or film IDs. Use for `films`; each entry is one film. | | `searchQuery` | string | One film-related search such as a title, director, cast member, or keyword. Use for `search`. Run each different search separately. | | `listUrlOrId` | string | One public Letterboxd list URL or list ID. Use for `list`. | | `browseMode` | string | Select `popular` for the `popular` target. | | `browsePeriod` | string | Popular-film period: `day`, `week`, `month`, `year`, or `all-time`. | | `genre` | string | Optional Letterboxd genre filter for popular films, such as `Drama`. | | `profileUrlOrUsername` | string | Public profile URL or username. Use for `profile` or `watched`. | | `includeReviews` | boolean | Adds public film review rows for `films`, `search`, `list`, and `popular` targets. Default: `false`. | | `reviewOrder` | string | Orders collected reviews as `popular`, `recent`, `earliest`, `highest-rated`, or `lowest-rated`. Default: `popular`. | | `completeReviewText` | boolean | Gets complete review text when the source provides only a shortened preview. Default: `false`. | | `maxItems` | integer | Optional stop point for `search`, `list`, `popular`, `profile`, or `watched`. Leave it empty to collect all available results until the source is exhausted. | **Example public input** ```json { "target": "films", "filmUrlsOrIds": [ "https://letterboxd.com/film/the-shawshank-redemption/" ], "includeReviews": false, "reviewOrder": "popular", "completeReviewText": false } ``` #### 🧾 Output **Film rows** | Field | Type | What it does | | --- | --- | --- | | `resultType` | string | Always `film` for a film row. | | `film.id` | string, optional | Stable Letterboxd film ID. | | `film.url` | URL | Public Letterboxd page for the film. | | `film.title` | string | Film title shown on Letterboxd. | | `film.releaseYear` | integer, optional | Film release year. | | `film.directors` | array of objects, optional | People credited as directors. | | `film.directors[].name` | string | Director name. | | `film.directors[].url` | URL, optional | Public director page. | | `film.cast` | array of objects, optional | People credited in the cast. | | `film.cast[].name` | string | Cast member name. | | `film.cast[].url` | URL, optional | Public cast member page. | | `film.genres` | array of strings, optional | Genres shown for the film. | | `film.runtimeMinutes` | integer, optional | Film runtime in minutes. | | `film.synopsis` | string, optional | Film synopsis or description. | | `film.posterUrl` | URL, optional | Film poster image URL. | | `film.averageRating` | number, optional | Public average Letterboxd rating. | | `film.ratingCount` | integer, optional | Number of public ratings used for the average. | | `film.writtenReviewCount` | integer, optional | Number of written reviews shown by Letterboxd. | | `film.watchCount` | integer, optional | Number of members who marked the film watched. | | `film.fanCount` | integer, optional | Number of members who marked the film as a favorite. | | `film.listCount` | integer, optional | Number of public lists that include the film. | | `film.countries` | array of strings, optional | Countries linked to the film. | | `film.languages` | array of strings, optional | Languages linked to the film. | | `film.productionCompanies` | array of strings, optional | Studios or production companies linked to the film. | | `film.tagline` | string, optional | Film tagline when available. | | `film.imdbId` | string, optional | IMDb identifier when shown. | | `film.tmdbId` | string, optional | TMDb identifier when shown. | | `searchQuery` | string, optional | Search text that found the film. | | `browse` | object, optional | Popular-film selection that found the film. | | `browse.mode` | string | Browse type, currently `popular`. | | `browse.period` | string | Browse period: `day`, `week`, `month`, `year`, or `all-time`. | | `browse.genre` | string, optional | Genre filter used for the browse selection. | **Genuine beta row** The film row below is shortened. The `cast` array is marked with `"..."` to keep the example small; the other shown values are from a successful current-beta run. ```json { "resultType": "film", "film": { "id": "51778", "url": "https://letterboxd.com/film/the-shawshank-redemption/", "title": "The Shawshank Redemption", "releaseYear": 1994, "directors": [ { "name": "Frank Darabont", "url": "https://letterboxd.com/director/frank-darabont/" } ], "cast": "...", "genres": [ "Crime", "Drama" ], "runtimeMinutes": 142, "synopsis": "Imprisoned in the 1940s for the double murder of his wife and her lover, upstanding banker Andy Dufresne begins a new life at the Shawshank prison, where he puts his accounting skills to work for an amoral warden. During his long stretch in prison, Dufresne comes to be admired by the other inmates -- including an older prisoner named Red -- for his integrity and unquenchable sense of hope.", "posterUrl": "https://a.ltrbxd.com/resized/sm/upload/7l/hn/46/uz/zGINvGjdlO6TJRu9wESQvWlOKVT-0-600-0-900-crop.jpg?v=8736d1c395", "averageRating": 4.6, "ratingCount": 3061992, "writtenReviewCount": 334133, "watchCount": null, "fanCount": 185000, "listCount": null, "countries": [ "USA" ], "languages": [ "English", "en" ], "productionCompanies": [ "Castle Rock Entertainment" ], "tagline": "Fear can hold you prisoner. Hope can set you free.", "imdbId": "tt0111161", "tmdbId": "278" } } ``` **Review rows** | Field | Type | What it does | | --- | --- | --- | | `resultType` | string | Always `review` for a review row. | | `film.id` | string, optional | Stable Letterboxd film ID for the reviewed film. | | `film.url` | URL | Public Letterboxd page for the reviewed film. | | `film.title` | string | Reviewed film title. | | `film.releaseYear` | integer, optional | Reviewed film release year. | | `film.directors` | array of objects, optional | Directors linked to the reviewed film. | | `film.directors[].name` | string | Director name. | | `film.directors[].url` | URL, optional | Public director page. | | `film.cast` | array of objects, optional | Cast linked to the reviewed film. | | `film.cast[].name` | string | Cast member name. | | `film.cast[].url` | URL, optional | Public cast member page. | | `film.genres` | array of strings, optional | Genres shown for the reviewed film. | | `film.runtimeMinutes` | integer, optional | Reviewed film runtime in minutes. | | `film.synopsis` | string, optional | Reviewed film synopsis or description. | | `film.posterUrl` | URL, optional | Reviewed film poster image URL. | | `film.averageRating` | number, optional | Public average Letterboxd rating for the film. | | `film.ratingCount` | integer, optional | Number of public film ratings. | | `film.writtenReviewCount` | integer, optional | Number of written film reviews shown by Letterboxd. | | `film.watchCount` | integer, optional | Number of members who marked the film watched. | | `film.fanCount` | integer, optional | Number of members who marked the film as a favorite. | | `film.listCount` | integer, optional | Number of public lists that include the film. | | `film.countries` | array of strings, optional | Countries linked to the film. | | `film.languages` | array of strings, optional | Languages linked to the film. | | `film.productionCompanies` | array of strings, optional | Studios or production companies linked to the film. | | `film.tagline` | string, optional | Film tagline when available. | | `film.imdbId` | string, optional | IMDb identifier when shown. | | `film.tmdbId` | string, optional | TMDb identifier when shown. | | `review.id` | string, optional | Stable Letterboxd review ID. | | `review.url` | URL | Public page for the review. | | `review.text` | string | Review text shown on Letterboxd. | | `review.rating` | number, optional | Rating given by the reviewer. | | `review.likes` | integer, optional | Number of likes shown for the review. | | `review.containsSpoilers` | boolean, optional | Whether Letterboxd marks the review as a spoiler. | | `review.postedAt` | string, optional | Review posting date or time when shown. | | `review.commentCount` | integer, optional | Number of comments shown for the review. | | `review.watched` | boolean, optional | Whether the reviewer marks the film as watched. | | `review.rewatched` | boolean, optional | Whether the reviewer marks this as a rewatch. | | `review.reviewer` | object | Public reviewer identity and profile link. | | `review.reviewer.username` | string | Letterboxd username of the reviewer. | | `review.reviewer.displayName` | string, optional | Reviewer name when shown. | | `review.reviewer.profileUrl` | URL | Public reviewer profile page. | | `review.reviewer.avatarUrl` | URL, optional | Reviewer profile image URL when shown. | | `searchQuery` | string, optional | Search text that found the film. | | `browse` | object, optional | Popular-film selection that found the film. | | `browse.mode` | string | Browse type, currently `popular`. | | `browse.period` | string | Browse period used for the selection. | | `browse.genre` | string, optional | Genre filter used for the selection. | **Profile rows** | Field | Type | What it does | | --- | --- | --- | | `resultType` | string | Always `profile` for a profile row. | | `profile.username` | string | Letterboxd username. | | `profile.displayName` | string, optional | Name shown for the profile. | | `profile.url` | URL | Public Letterboxd profile page. | | `profile.bio` | string, optional | Public profile biography. | | `profile.location` | string, optional | Public profile location. | | `profile.websiteUrl` | URL, optional | Public website linked from the profile. | | `profile.avatarUrl` | URL, optional | Profile image URL. | | `profile.joinedAt` | string, optional | Date the profile joined Letterboxd. | | `profile.stats` | object, optional | Public counts shown on the profile. | | `profile.stats.filmsWatchedCount` | integer, optional | Number of films marked watched. | | `profile.stats.ratingsCount` | integer, optional | Number of film ratings shown. | | `profile.stats.reviewsCount` | integer, optional | Number of written reviews shown. | | `profile.stats.listsCount` | integer, optional | Number of lists shown. | | `profile.stats.followersCount` | integer, optional | Number of followers shown. | | `profile.stats.followingCount` | integer, optional | Number of profiles followed. | | `profile.favorites` | array of objects, optional | Favorite films shown on the profile. | | `profile.favorites[].id` | string, optional | Stable film ID for a favorite. | | `profile.favorites[].url` | URL | Public page for a favorite film. | | `profile.favorites[].title` | string | Favorite film title. | | `profile.favorites[].releaseYear` | integer, optional | Favorite film release year. | | `profile.favorites[].posterUrl` | URL, optional | Favorite film poster URL. | | `profile.recentActivity` | array of objects, optional | Recent public activity shown on the profile. | | `profile.recentActivity[].activityType` | string | Activity type: `watched`, `reviewed`, `rated`, `liked`, or `rewatched`. | | `profile.recentActivity[].film` | object | Film linked to the activity. | | `profile.recentActivity[].film.id` | string, optional | Stable film ID for the activity film. | | `profile.recentActivity[].film.url` | URL | Public activity film page. | | `profile.recentActivity[].film.title` | string | Activity film title. | | `profile.recentActivity[].film.releaseYear` | integer, optional | Activity film release year. | | `profile.recentActivity[].film.posterUrl` | URL, optional | Activity film poster URL. | | `profile.recentActivity[].url` | URL, optional | Public page for the activity. | | `profile.recentActivity[].occurredAt` | string, optional | Activity date or time. | | `profile.recentActivity[].rating` | number, optional | Personal rating given by the profile. | | `profile.recentActivity[].rewatched` | boolean, optional | Whether the activity marks a rewatch. | **Genuine beta row** The profile row below is shortened. The favorites and recent activity arrays are marked with `"..."`; the shown identity and counts are from a successful current-beta run. ```json { "resultType": "profile", "profile": { "username": "calvinvaljean", "displayName": "Gabe Rodríguez", "url": "https://letterboxd.com/calvinvaljean/", "stats": { "filmsWatchedCount": 2577, "followersCount": 1282, "followingCount": 1718 }, "favorites": "...", "recentActivity": "..." } } ``` **Watched-film rows** | Field | Type | What it does | | --- | --- | --- | | `resultType` | string | Always `watchedFilm` for a watched-film row. | | `film.id` | string, optional | Stable Letterboxd film ID. | | `film.url` | URL | Public Letterboxd page for the film. | | `film.title` | string | Film title. | | `film.releaseYear` | integer, optional | Film release year. | | `film.directors` | array of objects, optional | Directors linked to the film. | | `film.directors[].name` | string | Director name. | | `film.directors[].url` | URL, optional | Public director page. | | `film.cast` | array of objects, optional | Cast linked to the film. | | `film.cast[].name` | string | Cast member name. | | `film.cast[].url` | URL, optional | Public cast member page. | | `film.genres` | array of strings, optional | Genres shown for the film. | | `film.runtimeMinutes` | integer, optional | Film runtime in minutes. | | `film.synopsis` | string, optional | Film synopsis or description. | | `film.posterUrl` | URL, optional | Film poster image URL. | | `film.averageRating` | number, optional | Public average Letterboxd rating. | | `film.ratingCount` | integer, optional | Number of public film ratings. | | `film.writtenReviewCount` | integer, optional | Number of written film reviews. | | `film.watchCount` | integer, optional | Number of members who marked the film watched. | | `film.fanCount` | integer, optional | Number of members who marked the film as a favorite. | | `film.listCount` | integer, optional | Number of public lists that include the film. | | `film.countries` | array of strings, optional | Countries linked to the film. | | `film.languages` | array of strings, optional | Languages linked to the film. | | `film.productionCompanies` | array of strings, optional | Studios or production companies linked to the film. | | `film.tagline` | string, optional | Film tagline when available. | | `film.imdbId` | string, optional | IMDb identifier when shown. | | `film.tmdbId` | string, optional | TMDb identifier when shown. | | `profile.username` | string | Letterboxd username for the watched history. | | `profile.displayName` | string, optional | Profile name when shown. | | `profile.url` | URL | Public profile page. | | `profile.bio` | string, optional | Public profile biography. | | `profile.location` | string, optional | Public profile location. | | `profile.websiteUrl` | URL, optional | Public website linked from the profile. | | `profile.avatarUrl` | URL, optional | Profile image URL. | | `profile.joinedAt` | string, optional | Date the profile joined Letterboxd. | | `profile.stats` | object, optional | Public profile counts. | | `profile.stats.filmsWatchedCount` | integer, optional | Number of films marked watched. | | `profile.stats.ratingsCount` | integer, optional | Number of film ratings shown. | | `profile.stats.reviewsCount` | integer, optional | Number of written reviews shown. | | `profile.stats.listsCount` | integer, optional | Number of lists shown. | | `profile.stats.followersCount` | integer, optional | Number of followers shown. | | `profile.stats.followingCount` | integer, optional | Number of profiles followed. | | `profile.favorites` | array of objects, optional | Favorite films shown on the profile. | | `profile.favorites[].id` | string, optional | Stable film ID for a favorite. | | `profile.favorites[].url` | URL | Public favorite film page. | | `profile.favorites[].title` | string | Favorite film title. | | `profile.favorites[].releaseYear` | integer, optional | Favorite film release year. | | `profile.favorites[].posterUrl` | URL, optional | Favorite film poster URL. | | `profile.recentActivity` | array of objects, optional | Recent public profile activity. | | `profile.recentActivity[].activityType` | string | Activity type. | | `profile.recentActivity[].film` | object | Film linked to the activity. | | `profile.recentActivity[].film.id` | string, optional | Stable activity film ID. | | `profile.recentActivity[].film.url` | URL | Public activity film page. | | `profile.recentActivity[].film.title` | string | Activity film title. | | `profile.recentActivity[].film.releaseYear` | integer, optional | Activity film release year. | | `profile.recentActivity[].film.posterUrl` | URL, optional | Activity film poster URL. | | `profile.recentActivity[].url` | URL, optional | Public activity page. | | `profile.recentActivity[].occurredAt` | string, optional | Activity date or time. | | `profile.recentActivity[].rating` | number, optional | Personal rating given by the profile. | | `profile.recentActivity[].rewatched` | boolean, optional | Whether the activity marks a rewatch. | | `watchedAt` | string, optional | Date or time when the profile marked the film watched. | | `personalRating` | number, optional | Rating the profile gave the film. | | `rewatched` | boolean, optional | Whether the profile marked the film as a rewatch. | **Genuine beta row** ```json { "resultType": "watchedFilm", "film": { "id": "1089088", "url": "https://letterboxd.com/film/coyote-vs-acme/", "title": "Coyote vs. Acme (2026)" }, "profile": { "username": "calvinvaljean", "url": "https://letterboxd.com/calvinvaljean/" } } ``` **List-entry rows** | Field | Type | What it does | | --- | --- | --- | | `resultType` | string | Always `listEntry` for a list-entry row. | | `film.id` | string, optional | Stable Letterboxd film ID. | | `film.url` | URL | Public Letterboxd page for the film. | | `film.title` | string | Film title. | | `film.releaseYear` | integer, optional | Film release year. | | `film.directors` | array of objects, optional | Directors linked to the film. | | `film.directors[].name` | string | Director name. | | `film.directors[].url` | URL, optional | Public director page. | | `film.cast` | array of objects, optional | Cast linked to the film. | | `film.cast[].name` | string | Cast member name. | | `film.cast[].url` | URL, optional | Public cast member page. | | `film.genres` | array of strings, optional | Genres shown for the film. | | `film.runtimeMinutes` | integer, optional | Film runtime in minutes. | | `film.synopsis` | string, optional | Film synopsis or description. | | `film.posterUrl` | URL, optional | Film poster image URL. | | `film.averageRating` | number, optional | Public average Letterboxd rating. | | `film.ratingCount` | integer, optional | Number of public film ratings. | | `film.writtenReviewCount` | integer, optional | Number of written film reviews. | | `film.watchCount` | integer, optional | Number of members who marked the film watched. | | `film.fanCount` | integer, optional | Number of members who marked the film as a favorite. | | `film.listCount` | integer, optional | Number of public lists that include the film. | | `film.countries` | array of strings, optional | Countries linked to the film. | | `film.languages` | array of strings, optional | Languages linked to the film. | | `film.productionCompanies` | array of strings, optional | Studios or production companies linked to the film. | | `film.tagline` | string, optional | Film tagline when available. | | `film.imdbId` | string, optional | IMDb identifier when shown. | | `film.tmdbId` | string, optional | TMDb identifier when shown. | | `list.id` | string, optional | Stable Letterboxd list ID. | | `list.url` | URL | Public Letterboxd list page. | | `list.name` | string | List name. | | `list.description` | string, optional | List description. | | `list.creator` | object, optional | Public identity of the list creator. | | `list.creator.username` | string | Creator username. | | `list.creator.displayName` | string, optional | Creator name when shown. | | `list.creator.profileUrl` | URL, optional | Public creator profile page. | | `position` | integer | Film position in the public list. | | `curatorNote` | string, optional | Note written by the list curator for this film. | **Genuine beta row** ```json { "resultType": "listEntry", "film": { "url": "https://letterboxd.com/film/harakiri/", "title": "Harakiri (1962)" }, "list": { "id": "207314", "url": "https://letterboxd.com/official/list/letterboxds-top-500-films/", "name": "Letterboxd's Top 500 Films", "description": "As of August 24, 2026. Curated by Dave Vis, extracted from here. This list ranks narrative feature films by average member rating. See all films that have entered this list and read about the history of Letterboxd’s all time official number one film. These list stats are unlocked for everybody!Changes from the latest update: (plus an archive of all previous updates)No new entriesEligibility rules:• There is a 25,000 minimum ratings threshold (note that these are different to watches!). See the top underseen films below the ratings threshold, curated by Sam Williams.• Films must be feature-length (more than 40 minutes long) with a festival premiere, theatrical distribution or professional streaming release.• This list excludes: documentaries of any kind, self-released web videos, DTV films, recap or recut films, theatre or stage shows, TV series, specials or episodes. TV movies are included.Official List HQ Directory | All Time Lists | Lists by Dave Vis", "creator": { "username": "official", "displayName": "Moderator dashboard", "profileUrl": "https://letterboxd.com/moderator/member/official/" } }, "position": 1 } ``` **Dataset output** The Output tab links to the dataset for this run. Rows use the shapes described above, so fields that do not apply to a row type are not required in that row. #### 💳 Pricing **Charge events** | Buyer-facing event | Price | When it applies | | --- | --- | --- | | Film | $0.0027 | One successfully extracted public film. | | Film review | $0.0027 | One successfully extracted public film review. | The pricing file lists these two charged outcomes. It does not define a separate event for empty or no-result work. #### 🔌 Integrations **Dataset access** Open the dataset output from the Output tab to export JSON or CSV, or use its Apify dataset link in another workflow. This Actor uses public Letterboxd pages and does not need a Letterboxd login or API key. **Video guide** https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4 #### ❓ FAQ ##### Can I add reviews to a film run? Yes. Turn on `includeReviews` for a film, search, list, or popular target. The run keeps film rows and adds public review rows when reviews are available. ##### What does Complete review text do? When a public review has a shortened preview, `completeReviewText` asks the Actor to retrieve the complete text that the source provides. ##### What happens when an optional Letterboxd field is missing? Some source fields are optional. A usable row can still be saved when Letterboxd does not show one of those fields. ##### Should I use a film URL or a film ID? For the `films` target, you can use either a public film URL or a film ID. Lists accept a URL or ID, and profiles accept a public profile URL or username. ##### Can I run several film searches together? No. Use one `searchQuery` per run and run each different search separately. ##### Do I need a Letterboxd login or API key? No. The Actor reads public Letterboxd pages and does not ask for Letterboxd account credentials or an API key. ##### Can this Actor change ratings, lists, or profiles? No. It collects public data only. It does not edit Letterboxd accounts or content. ### 📝 Changelog **0.0: Initial release** ### 🆘 Support For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~letterboxd/issues) and I'll fix or implement it in less than 24h 🫡 ### 🔗 Related Actors - [Letterboxd Film & Review Scraper — Ratings, No Login](https://apify.com/logiover/letterboxd-film-review-scraper): Compare film metadata and reviews with another public Letterboxd workflow. - [Letterboxd Film Pages Scraper](https://apify.com/parseforge/letterboxd-films-scraper): Build a flat film catalog from public Letterboxd pages. - [Letterboxd Scraper - Films, Reviews, Profiles & Lists](https://apify.com/zhorex/letterboxd-scraper): Explore film, review, profile, and list data in one alternate workflow. - [Letterboxd Film Reviews Scraper](https://apify.com/powerai/letterboxd-film-reviews-scraper): Focus on review text, reviewer details, and engagement fields. - [Letterboxd Scraper](https://apify.com/crawlerbros/letterboxd-scraper): Combine film metadata, popular films, and public profile data in another workflow. **Made with ❤️ by Maxime Dupré** # Actor input Schema ## `target` (type: `string`): Choose one source. Fields for other targets stay visible and are ignored. ## `filmUrlsOrIds` (type: `array`): Enter one or more public Letterboxd film URLs or film identifiers. Each entry is one film. Required when Target is Films. ## `searchQuery` (type: `string`): Enter one film-related search, such as a title, director, cast member, or keyword. Run each different search separately. Required when Target is Film search. ## `listUrlOrId` (type: `string`): Enter one public Letterboxd list URL or list identifier. Required when Target is Public list. ## `browseMode` (type: `string`): Browse popular films. Required when Target is Popular films. ## `browsePeriod` (type: `string`): Choose the period for popular films. Required when Target is Popular films. ## `genre` (type: `string`): Optionally filter Popular films by a Letterboxd genre name, such as Drama. Leave it empty for all genres. ## `profileUrlOrUsername` (type: `string`): Enter one public Letterboxd profile URL or username. Required when Target is Public profile or Watched films. ## `includeReviews` (type: `boolean`): Collect public film reviews with film results. Used by Films, Film search, Public list, and Popular films. Leave it off for film data only. ## `reviewOrder` (type: `string`): Choose the order for collected reviews. Used only when Include reviews is on. ## `completeReviewText` (type: `boolean`): Get complete review text when Letterboxd provides only a shortened preview. Used only when Include reviews is on. ## `maxItems` (type: `integer`): Optionally stop after this many output items for Film search, Public list, Popular films, Public profile, or Watched films. Leave it empty to collect all available results until the source is exhausted. ## Actor input object example ```json { "target": "films", "filmUrlsOrIds": [ "https://letterboxd.com/film/the-shawshank-redemption/" ], "includeReviews": false, "reviewOrder": "popular", "completeReviewText": false } ``` # Actor output Schema ## `dataset` (type: `string`): The result rows for this run. # 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 = { "target": "films", "filmUrlsOrIds": [ "https://letterboxd.com/film/the-shawshank-redemption/" ] }; // Run the Actor and wait for it to finish const run = await client.actor("maximedupre/letterboxd").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 = { "target": "films", "filmUrlsOrIds": ["https://letterboxd.com/film/the-shawshank-redemption/"], } # Run the Actor and wait for it to finish run = client.actor("maximedupre/letterboxd").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 '{ "target": "films", "filmUrlsOrIds": [ "https://letterboxd.com/film/the-shawshank-redemption/" ] }' | apify call maximedupre/letterboxd --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,maximedupre/letterboxd" } } } ``` 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/JkgyaO7zoU7Le1McH/builds/Gac3dbNaLLWmO1Npw/openapi.json