Letterboxd APIletterboxd.com ↗
Search Letterboxd's film catalog, fetch film details with community ratings, and retrieve user profiles, watchlists, and favorites via a simple REST API.
What is the Letterboxd API?
This API gives you access to Letterboxd data across 3 endpoints: search the film catalog by title, retrieve full film details including community rating and runtime, and pull user profile data covering bio, stats, favorites, watchlist, and follower lists. The get_film endpoint alone returns 7 fields per film, while get_user_profile surfaces favorites, likes, and followers in a single call.
curl -X GET 'https://api.parse.bot/scraper/dce779fe-5a60-4d3a-864c-c47bc53e42df/search_films?page=1&query=inception' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace letterboxd-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Letterboxd SDK — bounded, re-runnable; every call capped."""
from parse_apis.letterboxd_com_api import Letterboxd, NotFound
client = Letterboxd()
# Search for films by title query
for film in client.film_summaries.search(query="inception", limit=3):
print(film.title, film.year, film.director)
# Drill-down: take one search result and get full details
hit = client.film_summaries.search(query="inception", limit=1).first()
if hit:
full = hit.details()
print(full.title, full.year, full.runtime_minutes, full.rating)
# Fetch a user profile with favorites, watchlist, likes, and followers
try:
profile = client.user_profiles.get(username="bug39")
print(profile.display_name, profile.stats.films, profile.followers_count)
for fav in profile.favorites:
print(fav.title, fav.slug)
except NotFound as e:
print("user not found:", e)
# Fetch film details by slug, handling not-found
try:
film = client.films.get(slug="the-dark-knight")
print(film.title, film.director, film.runtime_minutes, film.rating)
except NotFound as e:
print("film not found:", e)
print("exercised: film_summaries.search, FilmSummary.details, films.get, user_profiles.get")
Full-text search over Letterboxd's film catalog. Returns title, year, director, URL, and slug for each match. Results are auto-iterated across pages; each page returns up to 20 films. Films without a listed director return null for that field.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for paginated results. |
| queryrequired | string | Search query to match against film titles. |
{
"type": "object",
"fields": {
"count": "number of films returned on this page",
"films": "array of film search results with title, year, director, url, and slug"
},
"sample": {
"count": 20,
"films": [
{
"url": "https://letterboxd.com/film/inception/",
"slug": "inception",
"year": "2010",
"title": "Inception",
"director": "Christopher Nolan"
}
]
}
}About the Letterboxd API
Film Search and Lookup
The search_films endpoint accepts a query string and returns paginated results — up to 20 films per page — each with title, year, director, url, and slug. The page parameter lets you iterate through deeper results. Films without a credited director return null for that field rather than an error, so handle that case in your client. Slugs returned here feed directly into get_film for full detail lookups.
Film Detail Data
get_film takes a Letterboxd URL slug (e.g. 'the-dark-knight') and returns the film's title, year, director, runtime_minutes, community rating out of 5, slug, and canonical url. The rating reflects the average of all user ratings logged on Letterboxd. If the slug does not match a known film, the endpoint returns an input_not_found response rather than an empty result.
User Profiles
get_user_profile takes a username and returns a structured profile object. The stats field contains films, following, and followers counts. favorites returns the user's pinned films with title, slug, and url. watchlist and likes each return the first page (approximately 28 items) with watchlist_count reflecting the user's total. The followers array includes each follower's display_name, username, and url. Accounts that don't exist return input_not_found.
The Letterboxd API is a managed, monitored endpoint for letterboxd.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when letterboxd.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official letterboxd.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a film recommendation tool seeded by a user's
favoritesandwatchlistentries. - Track community
ratingtrends across a director's filmography usingget_filmin bulk. - Map social graphs by crawling
followersarrays returned byget_user_profile. - Auto-complete film search in a movie tracking app using
search_filmswith thequeryparam. - Sync a user's Letterboxd
watchlistinto an external to-watch list or calendar. - Cross-reference
runtime_minutesandyeardata for film scheduling or curation tools. - Analyze which films appear most frequently in users'
likesacross a cohort of profiles.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Letterboxd have an official developer API?+
What does get_user_profile return for watchlists and likes?+
title, slug, and url. The watchlist_count field reflects the user's total watchlist size, so you can determine whether more entries exist beyond what's returned.Does the API return individual film reviews or diary entries?+
Does get_film return cast members or genre tags?+
get_film returns title, year, director, runtime_minutes, rating, slug, and url. Cast lists and genre classifications are not included in the current response shape. You can fork the API on Parse and revise it to add those fields.How does pagination work in search_films?+
page parameter to retrieve subsequent pages. The response includes a count field showing how many films were returned on that page, which helps you detect the last page when fewer than 20 results come back.