Skip to content

External Lists

External Lists let you populate smart lists from external services like MDBList, IMDb, Letterboxd, Trakt, TMDB, ListenBrainz, and Scrob. Use them to create collections based on trending lists, watchlists, top charts, curated lists, and music playlists 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

If a list can't be fetched (for example, the provider is down or there's a network error), every smart list that uses it is left unchanged for that refresh, and the refresh shows as failed with the list's URL. The next refresh tries again. Some providers report a failed request as an empty or shortened list instead (see Missing Items), and those are used as returned.

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. Music lists (ListenBrainz) are matched by MusicBrainz recording IDs instead, with a title + artist fallback for tracks that lack MusicBrainz tags.

Supported Providers

Provider API key required Matches by
MDBList Yes IMDb, TMDB, TVDB
IMDb No IMDb
Letterboxd No TMDB
ListenBrainz No (optional user token) MusicBrainz recording ID (title + artist fallback)
Scrob Yes TMDB, TVDB
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}
Official list https://mdblist.com/lists/official/{movies\|shows}/{listname}

The official JustWatch Streaming Charts list is a live top-20 chart. The country, period, provider and genre filters you pick on the MDBList website end up in the URL and are applied by the plugin, so copy the URL after choosing your filters. Some official lists shown on the website are not exposed by the MDBList API and return no items.

Examples:

External List / equals / https://mdblist.com/lists/linaspurinis/top-watched-movies-of-the-week
External List / equals / https://mdblist.com/lists/official/movies/justwatch-streaming-charts?locale=en_US&rank=7&provider=nfx

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.

ListenBrainz

ListenBrainz is an open music listening tracker from the MusicBrainz project. It hosts user-created playlists and generates personalized playlists like Weekly Jams, Weekly Exploration, and Daily Jams. ListenBrainz lists contain music tracks, so use them with the Audio media type.

Setup:

No API key required for public playlists. To access your private playlists, add a user token:

  1. Go to listenbrainz.org/settings
  2. Copy your User token
  3. Enter it in the plugin Settings tab under External Lists > ListenBrainz User Token

Supported URLs:

Type URL format
Playlist https://listenbrainz.org/playlist/{id}
Syndication feed https://listenbrainz.org/syndication-feed/user/{user}/recommendations?recommendation_type={type}

A playlist URL points to one specific playlist — its current contents are fetched on every refresh.

A syndication feed URL points to a type of generated playlist (e.g., weekly-jams, weekly-exploration, daily-jams) rather than one specific playlist. On every refresh, the plugin looks up the latest generated playlist of that type for the user, so your smart list automatically follows each new edition — ideal for Weekly Jams, which ListenBrainz regenerates every week. You can copy the syndication feed URL from the feed icon on a generated playlist on your ListenBrainz Created for you page.

Examples:

External List / equals / https://listenbrainz.org/playlist/07e984e3-1e63-44e3-b53c-7c3f9502cd28
External List / equals / https://listenbrainz.org/syndication-feed/user/rob/recommendations?recommendation_type=weekly-jams

How Music Matching Works

Tracks are matched by MusicBrainz recording IDs, which Jellyfin reads from your music files' embedded tags (e.g., files tagged with MusicBrainz Picard). Files tagged with a recording ID only match by that ID — they never fall back to title + artist matching. Untagged files fall back to title + artist matching, so untagged libraries work too — though tagged libraries will match more reliably. When several library items match the same track (e.g., the same song on an album, a compilation, and a live release), only the best match is added — an exact recording ID match is preferred, then a title match that didn't need a "(Live)"-style suffix stripped.

Private Playlists

Public playlists work without any configuration. To use your own private playlists, configure a ListenBrainz user token in the plugin settings (see Setup above).

Scrob

Scrob is a self-hosted media tracker with user-created lists. Because it's self-hosted, the admin configures the Scrob server URL and API key once for the whole plugin, in the same place as the other provider credentials.

Setup:

  1. Enter your Scrob server URL — the same URL you use in your browser, e.g. https://scrob.example.com — in the plugin Settings tab under External Lists > Scrob Server URL
  2. Go to your Scrob instance's Connections page and copy your API key
  3. Enter the API key under External Lists > Scrob API Key

Supported URLs:

Type URL format
User list {server}/list/{id}

Example:

External List / equals / https://scrob.example.com/list/12

List items are matched in the order Scrob returns them, so External List Order sort works the same as with the other providers.

List URLs Must Match the Configured Server

A list URL is only recognised when it uses the exact address configured in Settings — same scheme, host and port. If you configured https://scrob.example.com, then http://192.168.1.50:7330/list/12 won't be recognised even though it's the same Scrob instance.

Only Lists Visible to the Configured Account

The configured API key determines what's accessible: your own lists always work, and other users' lists work only if they're public. A private list belonging to a different Scrob user returns an error.

Note that this is a grant, not just a limit: one key is shared by the whole Jellyfin server, so every user allowed to create smart lists can reference any list that key can see — including the key owner's private lists. Use a Scrob account whose visibility you're happy to share.

Matching Requires TMDB IDs

Scrob doesn't store IMDb IDs — items match on TMDB ID, plus the series TVDB ID for season entries and the episode TVDB ID for episodes Scrob resolved from TVDB. Library items with none of those won't match.

Seasons Match the Whole Series

A season added to a Scrob list is matched as its parent series, so the rule pulls in the whole show rather than that one season. This is the same behaviour as season entries in Trakt lists. Person entries are ignored entirely.

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 app.trakt.tv/settings/apps/api
  2. Sign in to your Trakt account
  3. Click the + button in the top right to create a 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

A client ID is required even for public lists

The Trakt API has no anonymous access - every request must carry a client ID, so making a list public does not remove the need for one. If a Trakt list fails with "Trakt rejected the client ID", check that the app still exists under app.trakt.tv/settings/apps/api and that the client ID was copied correctly. Free Trakt accounts are limited to one connected application at a time.

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 more than one of the list's own external lists, its best (lowest) position among them is used for sorting. External lists used by other smart lists, or by this playlist's bumper rules, never affect the order.

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.

Missing Items

Missing items shows which entries of a list's external lists are not in your library, so you can see what to add. It is available on the admin configuration page only, for lists that have an External List rule: open it from the list card's ⋮ menu, or with the Missing items button on the expanded card.

For each external list, the dialog shows how many entries are missing, when the external list was last fetched, and a table of the missing entries: their position in the external list, title and year where known, type, and links to IMDb, TMDB and TVDB. Download CSV saves the missing entries of all the list's external lists to a spreadsheet file.

  • Uses the last fetch: Opening the dialog does not contact the provider. It uses each external list as it was last fetched by a refresh of this list, or of any other list with the same URL. To see current data, click Refresh (enable the list first if it is disabled), wait for the refresh to finish, then open Missing items again.
  • Empty until fetched: Fetched lists are kept in memory only. After a server restart, the dialog shows "No data yet" until a refresh fetches the list successfully. A fetch that fails with an error (for example, because the provider's API key is missing) leaves the last fetched data in place, or "No data yet" if there is none. Some providers report a failed request as an empty or shortened list instead, for example MDBList when its API returns an error, or an IMDb list that is private. That replaces the previous data, and the dialog then shows that the list returned no entries, or checks only the entries that were fetched.
  • Checks the whole server: Your library is checked live when you open the dialog, across all libraries on the server.
  • Matches like the rule: Movie entries are checked against movies, show entries against series (a show counts as present when the series is in your library), and episode entries against episodes. IMDb entries are checked against movies, series, episodes, music videos and videos whatever type IMDb gives them, as the External List rule does; the type is shown for reference only.
  • Titles depend on the provider: MDBList, Trakt, TMDB and IMDb entries include a title. Letterboxd and Scrob entries show IDs only.
  • Not checked: Music lists (ListenBrainz) are not supported. External List not equals rules and bumper rules are not included.

User-Agent

The plugin sends a User-Agent header when fetching external lists. Each provider has a sensible built-in default, but if a provider starts blocking the plugin's requests you can override the User-Agent in the plugin Settings tab under External Lists > User-Agent:

  • Default: Each provider uses its own built-in User-Agent (recommended).
  • Auto Clone: Uses your browser's User-Agent, automatically re-captured every time you open the SmartLists admin page.
  • Clone: Uses your browser's User-Agent, captured once when you save the settings.
  • Custom: Uses exactly the value you enter in the text field.

The clone modes capture the User-Agent from the browser you access the admin configuration page with. The override applies to all providers that send a User-Agent (IMDb, Letterboxd, Trakt, ListenBrainz, Scrob).

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.