Get a custom list
Returns a custom list’s metadata and its items.
Beta. The shape may still change; this page is updated when it does.
Reads only. Creating lists, editing them and adding or removing items are done on the website and are not yet part of the API.
Requires a PRO or VIP account
Custom lists is a paid feature. The request must carry an access token belonging to a Simkl PRO or VIP user — there is no anonymous access, because an anonymous caller is treated as a free account.
A free or anonymous caller does not get an error status. The response is HTTP 200 carrying a premium_only body instead of list data:
{
"error": "premium_only",
"message": "Custom list items are available to Simkl PRO and VIP members only.",
"item": {
"title": "Upgrade to Simkl PRO/VIP to unlock this list",
"description": "Subscribe to Simkl PRO or VIP to view this list",
"poster": "https://simkl.in/poster_upgrade.webp"
}
}
Three things to know about it, because each one breaks a naive client:
erroris lowercasepremium_only.- There is no
itemsarray and nopaginationobject. This is a different response shape, not a degraded one, soitemsis undefined rather than empty. itemis singular and renderable — it has a title, a description and a real poster URL, so you can drop it straight into your list view instead of leaving the user with a blank screen.
Check for an error key on a 200 before reading items. A client that branches only on the status code will treat this as a successful list and render the placeholder as though it were real content.
A missing list is indistinguishable
The tier check runs before the list is looked up, so for a free or anonymous caller a list ID that does not exist returns the same 200 premium_only body as a list that does. You cannot tell them apart without a PRO token. With a PRO or VIP token an unknown ID is a normal 404.
Sorting
sort here is not validated against a fixed list, unlike GET /lists/user/{userId}. An unrecognised value does not error — it falls back to the list’s own ordering. Omit sort to use the order the list owner chose, which is usually what you want.
Sorts that depend on a viewer’s own watch data resolve against the list owner, not the caller, so the same list looks the same to everyone and stays shareable.
Authorizations
A user access_token, sent as Authorization: Bearer .... Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. Every flow returns the same kind of token. See Set up authentication.
Path Parameters
Numeric list ID.
Query Parameters
Items per page, 1 to 500. Values outside that range are clamped silently rather than rejected, so asking for 99999 returns 500 and a 200.
A non-numeric value is normally 400 wrong_parameter, but on GET /lists/{id} that is not guaranteed: the edge cache coerces this parameter itself, so on a cache hit a malformed value is silently replaced with the default and answered 200. Validate paging input on your side rather than relying on a 400.
1 <= x <= 5001-based page number, also clamped silently. page times limit cannot exceed 10000, so deep paging is capped -- at the default limit of 50 the last reachable page is 200.
As with limit, a non-numeric value is normally 400 but can be silently defaulted on a cached GET /lists/{id} response.
x >= 1Sort direction. Anything other than asc or desc is a 400.
asc, desc Ordering token for the list's items.
Free-form rather than a closed set: an unrecognised token is accepted, not rejected, and is echoed back verbatim in the response's sort field, so that field tells you what you asked for and not what was applied. There is no error to detect a typo by -- check the returned order instead.
Two viewer-relative tokens are rewritten before use, and the rewritten form is what comes back: my-* becomes user-*, and last-watched becomes user-last-watched. These always resolve against the list owner's data, not yours, so the ordering is the same for everyone who reads the list.
Omit this parameter to use the list's own stored order. Note that supplying it at all changes the direction default: with no sort the list's stored direction applies, but with a sort the default becomes desc. ?sort=position therefore returns ["position","desc"] on a list whose own order is ["position","asc"] -- pass direction=asc if you meant to keep it.
full adds an overview field to every item.
full Response
The list, or a premium_only body if the caller is not PRO or VIP. Both are 200 -- check for an error key.
- Option 1
- Option 2
The list's metadata, merged with pagination and this page of items. Note top_items is always empty here.
Numeric list ID -- the value to pass to GET /lists/{id}.
216282
The list's title.
"Regular TV list"
URL-safe form of the name, for building a link to the list on simkl.com.
"regular-tv-list"
The list's blurb, in two lengths. Both are independently optional -- a list can have a short description and no full one, or neither.
What kind of title the list holds. A list is single-type. movies, tv and anime are the values you will see through the API today; the rest exist on Simkl but are not yet exposed here.
movies, tv, anime, manga, characters, companies "tv"
How the list is built. regular is hand-curated. auto is a saved Discover filter, so its contents change on their own and its counts.items can be very large. The rest are specialised list kinds.
regular, auto, favorite, voting, tier, import, recommendations "regular"
Who can read the list.
unlisted means reachable by link but not enumerable. Someone with the list ID can read it, but it will not appear when you list that user's lists -- only the owner sees their own unlisted lists there. So a library view built from GET /lists/user/{userId} shows public lists for other people, and public plus unlisted plus private for the signed-in user.
public, unlisted, private "public"
Whether the owner wants positions shown as visible rank numbers when the list is displayed. Presentation only -- it does not affect ordering.
false
The list's owner. On GET /lists/user/{userId} a followed or collaborated list carries its own owner here, not the user whose library you asked for.
Totals for the whole list, independent of the page you requested. items is the list's real size -- compare it with pagination.total_items, which reflects the current query.
Up to five preview entries for rendering a list card, in list order. Populated by GET /lists/user/{userId}; always empty on GET /lists/{id}, which returns the real items array instead.
Fewer than five entries means fewer than five of the list's titles can be previewed -- a title with no poster on file is skipped rather than returned without one. top_items is a preview strip, not a count of anything: use counts for totals.
5The ordering actually used for this response, as [token, direction]. With no ?sort this is the list's own stored order. Note that an unrecognised ?sort token is echoed back here verbatim, so this field confirms what you asked for rather than what was applied.
2 elementsWhen the list was last modified, UTC.
"2026-08-27T23:49:29Z"
When the list was created, UTC.
"2025-02-03T14:41:56Z"
This page of the list's titles.
Whether the owner has pinned this list. Type 2 null -- this field is omitted entirely unless you are reading your own library, so treat a missing pinned as "not applicable" rather than false. See Null and missing values.
false