Skip to content

Letterboxd User Films

Finds every movie in a Letterboxd user's watched films page.

The expected input is a username or a dictionary with the username and optional parameters. Multiple values are supported as either a list or a comma-separated string.

Kometa now uses letterboxdpy for Letterboxd access. The builder contract is unchanged, but watched-film ordering now follows the default order returned by letterboxdpy.

You can add different filters directly to this Builder.

Filter Attribute Description
username Description: Letterboxd username
Values: Username string (required)
sort_by Description: Accepted for compatibility with older configs.
Default: release_date_newest
Values: release_date_newest, release_date_earliest, name, popularity, when_added_newest, when_added_earliest, when_rated_newest, when_rated_earliest, average_rating_highest, average_rating_lowest, user_rating_highest, user_rating_lowest, length_shortest, length_longest
min_rating Description: Filter by minimum user rating (on 10-point scale)
Values: number from 0 to 10
limit Description: Max number of items per returned.
Values: number greater than 1
year Description: Search for the specified year range.
Values: range of int i.e. 1990-1999
note Description: Accepted for compatibility with older configs, but watched-film notes are not exposed by letterboxdpy and this filter is ignored.
Values: Any String
incremental Description: Accepted for compatibility with older configs.
Default: false at runtime
Values: true or false

The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated and in a specific order.

Sort, Note, and Incremental Behavior

sort_by values are still accepted so existing configs do not break, but letterboxdpy does not expose a stable way for Kometa to force those sort orders for watched films. Kometa therefore uses the default page order returned by letterboxdpy and logs a warning when a non-default sort_by is supplied.

note filtering is currently ignored for watched films because letterboxdpy does not expose watched-film notes for Kometa to match against.

incremental parsing is currently disabled for Letterboxd user films because letterboxdpy does not expose stable incremental state for Kometa to track. If incremental: true is set, Kometa logs a warning and continues with a normal full fetch.

Using the limit filter attribute is recommended when using a user with many watched films as the number of results returned could be very large.

Details Builder

You can replace letterboxd_user_films with letterboxd_user_films_details if you would like to use the details variant (currently no description is available for user pages, but this maintains consistency with other builders).

Example Letterboxd User Films Builder(s)

collections:
  User Watched Films:
    letterboxd_user_films: {username}
    collection_order: custom
    sync_mode: sync

collections:
  User Highly Rated Films:
    letterboxd_user_films:
      username: {username}
      min_rating: 8
      sort_by: user_rating_highest
    collection_order: custom
    sync_mode: sync

collections:
  User 90s Films:
    letterboxd_user_films:
      username: {username}
      year: 1990-1999
      sort_by: release_date_earliest
    collection_order: custom
    sync_mode: sync

collections:
  Multiple Users' Watched Films:
    letterboxd_user_films:
      - {username1}
      - {username2}
      - {username3}
    collection_order: custom
    sync_mode: sync

collections:
  Multiple Users' Highly Rated Films:
    letterboxd_user_films:
      - username: {username1}
        min_rating: 8
        sort_by: user_rating_highest
      - username: {username2}
        min_rating: 9
        sort_by: user_rating_highest
    collection_order: custom
    sync_mode: sync