Social Fetch
Start for freeStart free
Letterboxd hub

Letterboxd List API

One list with its description, tags, films, counts and its first 100 films.

GET /v1/letterboxd/users/{username}/lists/{slug}

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}/lists/{slug} returns data.list. The list carries slug, title, author, publishedAt, updatedAt, description, descriptionTruncated, tags, films, filmCount, likes, clones, visibility and url. films holds the first 100 film references of the list; there is no page or cursor parameter and no next page. filmCount is the list's total when available, so it can be larger than the number of films returned.

Some list slugs contain a colon, for example filmlist:89234618. Send it encoded as %3A in the path. When the description is longer than its opening part, the route returns the full description and keeps paragraph breaks, so descriptionTruncated is false when the whole text was returned. A list that does not exist returns not_found; a valid list with no films returns found with an empty films array.

Letterboxd List API FAQ

How many films of a long list do I get?

The first 100, in list order. The route takes no page or cursor, so a list with more than 100 films returns its first 100, and filmCount tells you the total.

What does descriptionTruncated mean?

True means only the start of the description is available. When the whole description is available, the route returns it and the flag is false.

Can a list slug contain a colon?

Yes. Some list slugs contain a colon, for example filmlist:89234618. Encode it in the path as %3A; the schema accepts letters, digits, dash, underscore, dot, tilde and colon.

What do clones and visibility mean?

clones is the number of times the list was cloned, when available. visibility is the visibility value, for example public. Both are nullable when not available.

How many credits does a list 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