Skip to content

External Lists

External Lists let you populate smart lists from external services like MDBList, IMDb, Letterboxd, Trakt, and TMDB. Use them to create collections based on trending lists, watchlists, top charts, and curated lists from these services.

How It Works

  1. Configure API key(s) in the plugin Settings tab under External Lists
  2. Create a rule with the External List field, equals operator, and the list URL as the value
  3. On refresh, the plugin fetches the external list and matches items by provider IDs (IMDb, TMDB, TVDB) against your Jellyfin library

Items are matched by comparing provider IDs between the external list and your library metadata. For episodes, the episode's own provider IDs are checked first. Parent series IDs are only used as a fallback when the external list entry represents a show/series, which lets show lists produce episode playlists without letting episode-level IDs match unrelated shows.

Supported Providers

Provider API key required Matches by
MDBList Yes IMDb, TMDB, TVDB
IMDb No IMDb
Letterboxd No TMDB
Trakt Yes (client ID) IMDb, TMDB, TVDB
TMDB Yes TMDB

Rate Limits

All providers have their own rate limits. Each list URL uses one or more requests depending on list size. Be mindful of how often you refresh these lists.

MDBList

MDBList aggregates lists from multiple sources and provides a unified API.

Setup:

  1. Go to mdblist.com/preferences
  2. Sign in or create a free account
  3. Scroll down to API Access and get your API key from there
  4. Enter the API key in the plugin Settings tab under External Lists > MDBList API Key

Supported URLs:

Type URL format
User list https://mdblist.com/lists/{username}/{listname}

Example:

External List / equals / https://mdblist.com/lists/linaspurinis/top-watched-movies-of-the-week

IMDb

IMDb public lists and chart pages can be used directly without an API key. The plugin uses IMDb's GraphQL API to fetch title IDs.

Setup:

No API key required. Just use a public IMDb list or chart URL.

Supported URLs:

Type URL format
User list https://www.imdb.com/list/{listid}/
Top 250 Movies https://www.imdb.com/chart/top/
Top 250 TV Shows https://www.imdb.com/chart/toptv/
Most Popular Movies https://www.imdb.com/chart/moviemeter/
Most Popular TV Shows https://www.imdb.com/chart/tvmeter/
Lowest Rated Movies https://www.imdb.com/chart/bottom/
Top English Movies https://www.imdb.com/chart/top-english-movies/
Awards/Event https://www.imdb.com/event/{eventid}/{year}/{instance}/
Awards + Category https://www.imdb.com/event/{eventid}/{year}/{instance}/#{category}

Examples:

External List / equals / https://www.imdb.com/chart/top/
External List / equals / https://www.imdb.com/event/ev0000003/2022/1/
External List / equals / https://www.imdb.com/event/ev0000003/2022/1/#oscar_best_sound

Awards/Event URLs

You can use IMDb event URLs to create lists of all titles nominated at a specific awards ceremony edition. The URL must include the event ID, year, and instance number — just copy the URL from the IMDb event page.

To filter by a specific award category, add a # fragment with the category slug. The slug is the category name in lowercase with spaces replaced by underscores, optionally prefixed with the event name (e.g., oscar_). Some common examples:

Event Category slug
Oscars - Best Picture #oscar_best_motion_picture_of_the_year
Oscars - Best Director #oscar_best_achievement_in_directing
Oscars - Best Sound #oscar_best_sound
Golden Globes - Best Drama #best_motion_picture_drama

Finding Category Slugs

The easiest way to find the correct category slug is to browse the event page on IMDb's website — the URL fragment updates as you select categories.

IMDb Limitations

IMDb lists must be public. Private lists cannot be accessed. Only IMDb IDs are extracted, so items in your library must have IMDb metadata to match.

Box Office Chart Removed

IMDb's /chart/boxoffice/ is no longer available via their API. Use Trakt's box office chart (https://trakt.tv/movies/boxoffice) as an alternative.

Letterboxd

Letterboxd is a social film discovery platform with user-curated lists and watchlists. The plugin scrapes the HTML pages to extract film data — no API key is required.

Setup:

No API key required. Just use a public Letterboxd list or watchlist URL.

Supported URLs:

Type URL format
User list https://letterboxd.com/{user}/list/{name}/
Watchlist https://letterboxd.com/{user}/watchlist/

Example:

External List / equals / https://letterboxd.com/official/list/letterboxds-top-500-films/

Letterboxd is Slow for Large Lists

Letterboxd list pages do not include TMDB IDs directly. The plugin must fetch each film's individual page to resolve its TMDB ID. This means a 250-film list requires ~250 additional HTTP requests, which can take several minutes. Resolved IDs are cached in memory for faster subsequent refreshes (until Jellyfin restarts). To minimize fetch time, use External List Order Ascending sort with a Max Items limit — the plugin will only fetch the first N items instead of the entire list.

Trakt

Trakt is a popular tracking service with user lists, watchlists, and curated charts. The plugin uses the Trakt API which requires a client ID.

Setup:

  1. Go to trakt.tv/oauth/applications
  2. Sign in to your Trakt account
  3. Click New Application
  4. Fill in the required fields:
    • Name: Jellyfin SmartLists (or any name you prefer)
    • Redirect uri: urn:ietf:wg:oauth:2.0:oob
    • All other fields can be left blank
  5. Click Save App
  6. Copy the Client ID from your new application
  7. Enter the client ID in the plugin Settings tab under External Lists > Trakt Client ID

Supported URLs:

Type URL format
User list https://trakt.tv/users/{user}/lists/{list}
Watchlist https://trakt.tv/users/{user}/watchlist
Trending movies https://trakt.tv/movies/trending
Popular movies https://trakt.tv/movies/popular
Most watched movies https://trakt.tv/movies/watched
Most played movies https://trakt.tv/movies/played
Most collected movies https://trakt.tv/movies/collected
Anticipated movies https://trakt.tv/movies/anticipated
Box office https://trakt.tv/movies/boxoffice
Trending shows https://trakt.tv/shows/trending
Popular shows https://trakt.tv/shows/popular
Most watched shows https://trakt.tv/shows/watched
Most played shows https://trakt.tv/shows/played
Most collected shows https://trakt.tv/shows/collected
Anticipated shows https://trakt.tv/shows/anticipated

Examples:

External List / equals / https://trakt.tv/users/justin/lists/imdb-top-rated-movies
External List / equals / https://trakt.tv/movies/trending

Public Lists Only

The plugin uses API-key authentication (not OAuth), so only public user lists and watchlists are accessible. Private lists require the list owner to make them public.

Episode-Level Lists

Trakt lists that contain individual episodes (e.g., a chronological viewing order across multiple series) are supported. Each episode is matched by its own provider IDs and preserves its position in the list. Use External List Order Ascending sort to maintain the list creator's intended episode order.

TMDB

The Movie Database (TMDB) provides a comprehensive API with user lists, popular/top-rated charts, and trending endpoints.

Setup:

  1. Go to themoviedb.org/settings/api
  2. Sign in or create a free account
  3. Click Create or Request an API Key and select Developer
  4. Accept the terms of use
  5. Fill in the application form:
    • Application Name: Jellyfin SmartLists (or any name you prefer)
    • Application URL: e.g. your Jellyfin server URL
    • Type of Use: Personal
    • Application Summary: e.g. Jellyfin plugin that creates smart playlists from TMDB lists and charts
    • Fill in the remaining contact fields with your information
  6. Submit the form — the API key is generated immediately
  7. Copy the API Key (v3 auth) — not the read access token
  8. Enter the API key in the plugin Settings tab under External Lists > TMDB API Key

Supported URLs:

Type URL format
User list https://www.themoviedb.org/list/{id}
Movie collection https://www.themoviedb.org/collection/{id}
Popular movies https://www.themoviedb.org/movie
Top rated movies https://www.themoviedb.org/movie/top-rated
Now playing movies https://www.themoviedb.org/movie/now-playing
Upcoming movies https://www.themoviedb.org/movie/upcoming
Popular TV https://www.themoviedb.org/tv
Top rated TV https://www.themoviedb.org/tv/top-rated
Airing today TV https://www.themoviedb.org/tv/airing-today
On the air TV https://www.themoviedb.org/tv/on-the-air
Trending (daily) https://www.themoviedb.org/trending/movie/day
Trending (weekly) https://www.themoviedb.org/trending/movie/week
Trending TV (daily) https://www.themoviedb.org/trending/tv/day
Trending TV (weekly) https://www.themoviedb.org/trending/tv/week
Trending all (weekly) https://www.themoviedb.org/trending/all/week

Examples:

External List / equals / https://www.themoviedb.org/movie
External List / equals / https://www.themoviedb.org/movie/top-rated
External List / equals / https://www.themoviedb.org/list/8136
External List / equals / https://www.themoviedb.org/collection/29

Trending URLs

The trending URLs (e.g. /trending/movie/week) are not browsable pages on TMDB's website — they map directly to TMDB API endpoints. Use the exact URL formats shown in the table above.

Sorting by External List Order

You can sort items in the same order as they appear in the external list. Select External List Order as the sort option (it appears in the sort dropdown when an External List rule is present).

  • Ascending: Items appear in the same order as the external list (position 1 first)
  • Descending: Items appear in reverse order (last item in the list first)

Items that are not matched by any external list are placed at the end.

If an item appears in multiple external lists, its best (lowest) position across all lists is used for sorting.

Example:

Rules: External List / equals / https://www.imdb.com/chart/top/
Sort:  External List Order / Ascending

This creates a collection sorted exactly like IMDb's Top 250 chart.

Tips

Combining with other rules

External list rules work well combined with other filters. For example:

  • External List equals <trending-list> AND Genre equals Action — trending action movies
  • External List equals <top-250> AND Playback Status equals Unplayed — unwatched top-rated movies
  • External List not equals <watched-list> — items not in a specific list

Multiple external lists

You can use multiple External List rules in different rule groups (OR logic) to combine items from several lists into one smart list.

Optimize external list performance

When using External List Order Ascending sort with a Max Items limit (e.g., 50), the plugin only fetches the first 50 items from the external list instead of the entire list. This is especially beneficial for Letterboxd (which requires per-film HTTP requests), but improves performance for all providers with large lists. This optimization does not apply to other sort options — the entire list must be fetched first to determine the final sort order.