Skip to main content
GET
Get a custom list

Authorizations

Authorization
string
header
default:YOUR_ACCESS_TOKEN
required

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

id
integer
required

Numeric list ID.

Query Parameters

limit
integer
default:50

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.

Required range: 1 <= x <= 500
page
integer
default:1

1-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.

Required range: x >= 1
direction
enum<string>

Sort direction. Anything other than asc or desc is a 400.

Available options:
asc,
desc
sort
string

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.

extended
enum<string>

full adds an overview field to every item.

Available options:
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.

The list's metadata, merged with pagination and this page of items. Note top_items is always empty here.

id
integer
required

Numeric list ID -- the value to pass to GET /lists/{id}.

Example:

216282

name
string
required

The list's title.

Example:

"Regular TV list"

slug
string
required

URL-safe form of the name, for building a link to the list on simkl.com.

Example:

"regular-tv-list"

description
object
required

The list's blurb, in two lengths. Both are independently optional -- a list can have a short description and no full one, or neither.

media_type
enum<string>
required

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.

Available options:
movies,
tv,
anime,
manga,
characters,
companies
Example:

"tv"

type
enum<string>
required

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.

Available options:
regular,
auto,
favorite,
voting,
tier,
import,
recommendations
Example:

"regular"

privacy
enum<string>
required

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.

Available options:
public,
unlisted,
private
Example:

"public"

display_number
boolean
required

Whether the owner wants positions shown as visible rank numbers when the list is displayed. Presentation only -- it does not affect ordering.

Example:

false

user
object
required

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.

counts
object
required

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.

top_items
object[]
required

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.

Maximum array length: 5
sort
string[]
required

The 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.

Required array length: 2 elements
Example:
updated_at
string<date-time>
required

When the list was last modified, UTC.

Example:

"2026-08-27T23:49:29Z"

created_at
string<date-time>
required

When the list was created, UTC.

Example:

"2025-02-03T14:41:56Z"

pagination
object
required
items
object[]
required

This page of the list's titles.

pinned
boolean

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.

Example:

false