Film & TV
Letterboxd API
Retrieve Letterboxd films, filmographies, member profiles, diaries, watched films, watchlists, reviews, lists, activity feeds and followers.
Look up any film with its rating, cast, crew, releases, popular reviews and IMDb and TMDB IDs, list a director's or actor's filmography, and read a member's profile, stats, activity feed, diary, watched films, watchlist, reviews, lists and network.
API availability: Available
http://localhost:3059Public API: https://api.scrapeatlas.com.Endpoints
/v1/letterboxd/filmGet a Letterboxd film
Get a film by slug, letterboxd.com URL or boxd.it short link, with its average rating and counts, cast with characters, crew, studios, countries, languages, genres, themes, releases, popular reviews, similar films and IMDb and TMDB IDs.
Reference/v1/letterboxd/personGet a Letterboxd filmography
Get a director's, actor's or other crew member's Letterboxd page with biography, portrait, TMDB ID, every role they have credits for and the films in the selected role.
Reference/v1/letterboxd/profileGet a Letterboxd profile
Get a member's display name, avatar, bio, location, website, four favorite films and, when public, their all-time stats.
Reference/v1/letterboxd/user-feedList a Letterboxd member's activity
List a member's latest diary entries, reviews with full text and lists, with ratings, likes, rewatches, watched dates and TMDB IDs.
Reference/v1/letterboxd/user-diaryList a Letterboxd member's diary
List a member's most recent diary entries with watched date, film, rating, like, rewatch and review flags.
Reference/v1/letterboxd/user-filmsList a Letterboxd member's watched films
List the films a member has watched most recently, with their rating, like and review link.
Reference/v1/letterboxd/user-watchlistList a Letterboxd member's watchlist
List the films most recently added to a member's watchlist and the watchlist's total size.
Reference/v1/letterboxd/user-reviewsList a Letterboxd member's reviews
List a member's most recent reviews with film, rating, like, rewatch, watched date, spoiler flag, text, likes and comments.
Reference/v1/letterboxd/user-listsList a Letterboxd member's lists
List a member's lists with name, film count, likes, comments, notes and preview films.
Reference/v1/letterboxd/user-connectionsList a Letterboxd member's network
List the members a member follows, or their followers, with display names, avatars and their own follower and following counts.
ReferenceQuick start
Create an API key on your account page, then call the public API. Values below are placeholders.
curl "https://api.scrapeatlas.com/v1/letterboxd/film?slug=parasite-2019" \
-H "x-api-key: YOUR_API_KEY"Coverage & limits
- Film: a slug, a letterboxd.com film URL or a boxd.it short link; provide exactly one of slug or url. Person: a slug with an optional role (default actor), or a letterboxd.com person URL. Username: 1 to 30 letters, digits or underscores.
- Member listings return their first page: Letterboxd's pages hold 50 diary entries, 72 watched films, 28 watchlist films, 12 reviews, 12 lists and 25 network members, and the declared caps are 50 diary entries, 100 watched or watchlist films, 20 reviews, 30 lists and 30 network members. Activity feeds return up to 100 items. Films return at most 100 cast members, 200 crew credits, 200 releases, 12 popular reviews and 12 similar films; filmographies at most 500 films; profiles at most 4 favourite films.
- Each upstream read (headers and body) has a 15-second deadline and each operation a 30-second deadline, including the queue wait. Decoded pages are capped at 3 MiB and JSON at 256 KiB.
- At most four upstream requests per operation: a short link to a renamed film reads its redirect, the old film page and the renamed page, and a profile its card and stats page, plus one shared retry after a network failure or HTTP 5xx.
- At most six active requests and twelve queued requests, with a queue wait of at most 10 seconds.
- Fixed origins letterboxd.com and boxd.it. No login, cookies, image downloads or result storage. The service API key is never forwarded.
| HTTP | failure.code | Meaning |
|---|---|---|
| 200 | partial | Usable data with named first-page, invalid-item, record-limit, field or stats warnings. |
| 400 | invalid_request | Missing, duplicate, malformed or unsupported parameters. |
| 401 | unauthorized | Missing or invalid worker API key. |
| 404 | not_found | The requested Letterboxd film, person or member was not found. |
| 403 | restricted_page | The member keeps the requested page, such as a watchlist, private. |
| 422 | unsupported_page | The Letterboxd page structure or identity could not be mapped. |
| 502 | upstream_challenged | Letterboxd challenged retrieval. |
| 502 | upstream_rate_limited | Letterboxd rate-limited retrieval. |
| 502 | upstream_error | Source retrieval did not complete. |
| 502 | response_too_large | Decoded source bytes exceeded the request limit. |
| 502 | unsafe_redirect | Letterboxd redirected outside the requested page. |
| 502 | request_limit | The upstream request budget was exhausted. |
| 503 | busy | Worker request or queue capacity was exceeded. |
| 504 | timeout | The operation deadline expired. |