> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/letterboxd/users-username-watchlist>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/letterboxd/users-username-watchlist.mdx>

---

# 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` 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.

## Request

- **Endpoint:** `GET /v1/letterboxd/users/{username}/watchlist`
- **Credits:** 1 credit
Failed requests are free
A not-found answer is still charged
- **Input:** by username
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/letterboxd/users/username/watchlist/get)
- **Platform page:** [/platforms/letterboxd](https://www.socialfetch.dev/platforms/letterboxd)

## 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.