Skip to main content
Custom lists are user-curated collections — “Best of 2026”, “Comfort rewatches”, “Anime to show my sister”. This API reads them.
Custom lists requires AUTH V2, and is a PRO and VIP feature. It is the first API that V1 client_ids cannot reach. There is no anonymous access either. Every call needs an Authorization: Bearer ... token belonging to a Simkl PRO or VIP account. An anonymous caller counts as a free account, so calling without a token does not get you a public subset — it gets you the premium_only body described below.Users can upgrade at simkl.com/vip.
Beta. The response shape may still change. These pages are updated when it does, and the changelog records anything that would break a client.

​
What you can and cannot do

Writes are on the roadmap. Until they land, an app can display lists but not edit them. Two fields help you lay lists out the way simkl.com does:
  • role on every list from GET /lists/user/{userId} — owner, collaborator or follower — so you can group a user’s own lists apart from the ones they follow or help edit. See Read a custom list.
  • collection on GET /lists/{id} — the sibling lists this one belongs with, such as a franchise split into Movies and TV Shows; null when it stands alone. See Lists that belong together, and Custom List Collections for how users create one.

​
A 200 does not always mean a list

A free or anonymous caller gets HTTP 200, not an error. The body carries premium_only rather than list data:
Check for an error key on a 200 before you read items. A client that branches only on the status code treats this as a successful list and renders the placeholder as real content — a user sees one fake entry titled “Upgrade to Simkl PRO/VIP” sitting in what looks like their list.Three details worth pinning down:
  • error is lowercase premium_only.
  • There is no items array and no pagination object here. This is a different shape, not a degraded one, so items is undefined rather than empty.
  • item is singular and renderable — real title, description and poster URL. Displaying it as-is is the simplest way to show the user why the list is empty.

​
Shared query parameters

Both endpoints accept the same paging controls. A non-numeric limit or page is normally a 400 naming the parameter, so out-of-range is silent while wrong-type is loud.
On GET /lists/{id} that validation is not guaranteed. That endpoint is served from an edge cache which coerces limit and page itself before deciding what to return. When the request hits a cached entry, a malformed limit=abc is silently replaced with the default and answered 200 rather than rejected — verified against production.So the same malformed request can return 400 or 200 depending only on whether that list happens to be cached. Validate your own paging input; do not rely on a 400 to catch it. direction is checked verbatim and always rejects, and GET /lists/user/{userId} is not edge-cached, so both of those behave predictably.
The two endpoints validate sort differently, on purpose.On GET /lists/user/{userId}, sort is a fixed set — updated, created, name, likes, followers, items, popularity — and anything else is a 400.On GET /lists/{id} it is free-form: an unrecognised value falls back to the list’s own stored order rather than erroring. Do not rely on a typo failing loudly there.

​
Knowing when to refetch

Neither endpoint should be polled on a timer. GET /sync/activities carries a custom_lists block that tells you whether anything changed, for the cost of one request:
Gate on all, then branch on the four buckets to refresh only the kind that moved — a user favouriting one show moves favorites and nothing else, so it costs one list refresh rather than a full re-read. The sync guide has the full pattern.
Two things to get right. The timestamps are nested one level deeper than every other block on that endpoint — read custom_lists.lists.all, not custom_lists.all. And the bucket is favorites (plural) while a list’s own type field is favorite (singular); a lookup keyed on one silently misses the other.
The custom_lists block is returned to AUTH V1 apps too, even though the two endpoints on this page require V2. A V1 app can see that lists changed without being able to read them — which is a reasonable prompt to migrate, and nothing more.

​
Account limits

These are limits on what a user can build, enforced when a list is saved on the website. The read API cannot return them, but they explain why a list stops accepting items. There are three separate ceilings, and a user can hit any of them independently: too many items in one list, too many lists, or too many items across everything.

​
See also

GET /lists/{id}

One list and its items, with sorting and paging.

GET /lists/user/{userId}

Every list belonging to one user.

Custom lists guide

What custom lists are, and how they fit alongside the watchlist.

AUTH V2

How to get the user token these endpoints require.