Social Fetch
Start for freeStart free
Letterboxd hub

Letterboxd Watchlist API

A member's public watchlist as film references, with a typed restricted answer for a private one.

GET /v1/letterboxd/users/{username}/watchlist

1 credit Failed requests are free A not-found answer is still charged

Try in playgroundFull API docs

About this endpoint

GET /v1/letterboxd/users/{username}/watchlist returns data.user, data.totalFilms, and data.films. totalFilms is the number of films on the watchlist. Each entry is a film reference with slug, id, shortCode, shortUrl, title and year. One call returns the first 28 films; there is no page or cursor parameter and no next page.

The watchlist can answer three ways. found means the list is public and films holds the first 28 films. restricted means the member's watchlist is private, so no films are returned and user carries the username you asked for with the other header fields null. not_found means the member does not exist. Check lookupStatus before treating an empty films array as a public empty watchlist.

Letterboxd Watchlist API FAQ

Can I read a private watchlist?

No. A private watchlist returns lookupStatus restricted with an empty films array. Only public watchlists return films.

How many films does one call return?

28. The route takes no page or cursor, and totalFilms is the full count.

Why is an empty watchlist found rather than not_found?

found describes the member and the visibility of the list, not whether it has films. A public member with nothing on their watchlist is a found result with an empty films array. not_found is reserved for a member that does not exist.

How many credits does a watchlist lookup cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

Other Letterboxd endpoints