Get a user's custom lists

curl --request GET \
  --url https://api.simkl.com/lists/user/{userId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.simkl.com/lists/user/{userId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.simkl.com/lists/user/{userId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/lists/user/{userId}")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

import Foundation

let url = URL(string: "https://api.simkl.com/lists/user/{userId}")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = ["Authorization": "Bearer <token>"]

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

const url = 'https://api.simkl.com/lists/user/{userId}';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simkl.com/lists/user/{userId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/lists/user/{userId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/lists/user/{userId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/lists/user/{userId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.simkl.com/lists/user/{userId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/lists/user/{userId}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/lists/user/{userId}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_items": 2,
    "total_pages": 1
  },
  "lists": [
    {
      "id": 216282,
      "name": "Regular TV list",
      "slug": "regular-tv-list",
      "description": {
        "short": "Regular TV list short des",
        "full": "Regular TV list full desc"
      },
      "media_type": "tv",
      "type": "regular",
      "privacy": "public",
      "display_number": false,
      "user": {
        "id": 8199460,
        "name": "testweek",
        "avatar": "https://us.simkl.in/img_tv/ico_profile_guest.png"
      },
      "counts": {
        "items": 2,
        "likes": 0,
        "followers": 0,
        "comments": 0,
        "collaborators": 0
      },
      "top_items": [
        {
          "id": 1482762,
          "type": "tv",
          "poster": "18/1878863979e76dbabf"
        },
        {
          "id": 3074490,
          "type": "tv",
          "poster": "20/20551481e9a270354e"
        }
      ],
      "sort": [
        "position",
        "asc"
      ],
      "updated_at": "2026-09-16T02:24:09Z",
      "created_at": "2026-09-16T02:24:09Z",
      "pinned": false
    },
    {
      "id": 76609,
      "name": "Best Mindfucks (Anime)",
      "slug": "best-mindfucks-anime",
      "description": {
        "short": "Some anime entertain. These ones break your brain, reconstruct it, then break it again.",
        "full": "Ever watched an anime that left you staring at the screen in shock, scrambling to piece together what just happened?"
      },
      "media_type": "anime",
      "type": "regular",
      "privacy": "public",
      "display_number": false,
      "user": {
        "id": 5,
        "name": "SIMKL",
        "avatar": "https://simkl.in/avatars/5/5_100.jpg?1682980938"
      },
      "counts": {
        "items": 222,
        "likes": 95,
        "followers": 104,
        "comments": 0,
        "collaborators": 1
      },
      "top_items": [
        {
          "id": 50250,
          "type": "anime",
          "poster": "83/83063509ab6ef28d2"
        },
        {
          "id": 37513,
          "type": "anime",
          "poster": "40/403690524472ac8"
        },
        {
          "id": 38960,
          "type": "anime",
          "poster": "10/10231814c8fe114faf"
        },
        {
          "id": 39687,
          "type": "anime",
          "poster": "23/23563e7856a42e5"
        },
        {
          "id": 39608,
          "type": "anime",
          "poster": "85/8568962a88c7c35"
        },
        {
          "id": 1536163,
          "type": "anime",
          "poster": "12/1278631554e130eb92"
        },
        {
          "id": 503490,
          "type": "anime",
          "poster": "31/3150974789b5b8ac2"
        }
      ],
      "sort": [
        "position",
        "asc"
      ],
      "updated_at": "2026-08-27T23:49:29Z",
      "created_at": "2025-02-03T14:41:56Z",
      "pinned": false
    }
  ]
}

{
  "error": "wrong_parameter",
  "code": 400,
  "message": "Invalid sort parameter"
}

{
  "error": "url_failed",
  "code": 404,
  "message": "User not found"
}

Get a user's custom lists

Returns the custom lists belonging to one user, with pagination.

Beta. The shape may still change; this page is updated when it does.

Viewing your own account returns your private and unlisted lists too, and adds a pinned flag to each one. Viewing someone else’s returns only what they have made visible, and has no pinned field.

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:

error is lowercase premium_only.
There is no items array and no pagination object. This is a different response shape, not a degraded one, so items is undefined rather than empty.
item is 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.

Sorting

sort here is validated against a fixed set, unlike GET /lists/{id}. An unrecognised value is a 400 rather than a silent fallback.

GET

lists

user

{userId}

Get a user's custom lists

curl --request GET \
  --url https://api.simkl.com/lists/user/{userId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.simkl.com/lists/user/{userId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.simkl.com/lists/user/{userId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/lists/user/{userId}")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

import Foundation

let url = URL(string: "https://api.simkl.com/lists/user/{userId}")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = ["Authorization": "Bearer <token>"]

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

const url = 'https://api.simkl.com/lists/user/{userId}';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simkl.com/lists/user/{userId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/lists/user/{userId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/lists/user/{userId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/lists/user/{userId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.simkl.com/lists/user/{userId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/lists/user/{userId}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/lists/user/{userId}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_items": 2,
    "total_pages": 1
  },
  "lists": [
    {
      "id": 216282,
      "name": "Regular TV list",
      "slug": "regular-tv-list",
      "description": {
        "short": "Regular TV list short des",
        "full": "Regular TV list full desc"
      },
      "media_type": "tv",
      "type": "regular",
      "privacy": "public",
      "display_number": false,
      "user": {
        "id": 8199460,
        "name": "testweek",
        "avatar": "https://us.simkl.in/img_tv/ico_profile_guest.png"
      },
      "counts": {
        "items": 2,
        "likes": 0,
        "followers": 0,
        "comments": 0,
        "collaborators": 0
      },
      "top_items": [
        {
          "id": 1482762,
          "type": "tv",
          "poster": "18/1878863979e76dbabf"
        },
        {
          "id": 3074490,
          "type": "tv",
          "poster": "20/20551481e9a270354e"
        }
      ],
      "sort": [
        "position",
        "asc"
      ],
      "updated_at": "2026-09-16T02:24:09Z",
      "created_at": "2026-09-16T02:24:09Z",
      "pinned": false
    },
    {
      "id": 76609,
      "name": "Best Mindfucks (Anime)",
      "slug": "best-mindfucks-anime",
      "description": {
        "short": "Some anime entertain. These ones break your brain, reconstruct it, then break it again.",
        "full": "Ever watched an anime that left you staring at the screen in shock, scrambling to piece together what just happened?"
      },
      "media_type": "anime",
      "type": "regular",
      "privacy": "public",
      "display_number": false,
      "user": {
        "id": 5,
        "name": "SIMKL",
        "avatar": "https://simkl.in/avatars/5/5_100.jpg?1682980938"
      },
      "counts": {
        "items": 222,
        "likes": 95,
        "followers": 104,
        "comments": 0,
        "collaborators": 1
      },
      "top_items": [
        {
          "id": 50250,
          "type": "anime",
          "poster": "83/83063509ab6ef28d2"
        },
        {
          "id": 37513,
          "type": "anime",
          "poster": "40/403690524472ac8"
        },
        {
          "id": 38960,
          "type": "anime",
          "poster": "10/10231814c8fe114faf"
        },
        {
          "id": 39687,
          "type": "anime",
          "poster": "23/23563e7856a42e5"
        },
        {
          "id": 39608,
          "type": "anime",
          "poster": "85/8568962a88c7c35"
        },
        {
          "id": 1536163,
          "type": "anime",
          "poster": "12/1278631554e130eb92"
        },
        {
          "id": 503490,
          "type": "anime",
          "poster": "31/3150974789b5b8ac2"
        }
      ],
      "sort": [
        "position",
        "asc"
      ],
      "updated_at": "2026-08-27T23:49:29Z",
      "created_at": "2025-02-03T14:41:56Z",
      "pinned": false
    }
  ]
}

{
  "error": "wrong_parameter",
  "code": 400,
  "message": "Invalid sort parameter"
}

{
  "error": "url_failed",
  "code": 404,
  "message": "User not found"
}

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

userId

integer

required

Numeric Simkl user 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

enum<string>

default:updated

Ordering. Anything outside this set is a 400.

Available options:

updated,

created,

name,

likes,

followers,

items,

popularity

followed

enum<string>

Set to the literal string true to include lists the user follows. 1, yes and on do nothing.

Available options:

true

collaborants

enum<string>

Set to the literal string true to include lists the user collaborates on. Only meaningful when viewing your own account.

Available options:

true

Response

The user's lists. This route has no PRO or VIP gate -- unlike GET /lists/{id}, an anonymous caller gets the real payload.

Pagination plus the lists array.

pagination

object

required

Hide child attributes

pagination.page

integer

required

The page actually returned, after clamping.

pagination.limit

integer

required

The page size actually used, after clamping.

pagination.total_items

integer

required

Total matching items.

pagination.total_pages

integer

required

Total pages at this limit. Remember the page times limit cap of 10000 -- this can report more pages than you are allowed to reach.

lists

object[]

required

One entry per list. Reading your own library adds a pinned flag to every entry, including followed and collaborated ones.

Hide child attributes

lists.id

integer

required

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

Example:

216282

lists.name

string

required

The list's title.

Example:

"Regular TV list"

lists.slug

string

required

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

Example:

"regular-tv-list"

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

Hide child attributes

lists.description.short

string | null

required

Type 4 null -- the owner has not written a short description. See Null and missing values.

Example:

"Some anime entertain. These ones break your brain, reconstruct it, then break it again."

lists.description.full

string | null

required

Type 4 null -- the owner has not written a full description. See Null and missing values. May contain newlines.

Example:

"Ever watched an anime that left you staring at the screen in shock?\n\nFrom psychological labyrinths to existential nightmares, these anime are designed to mess with your mind."

lists.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"

lists.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"

lists.privacy

enum<string>

required

Who can read the list.

Value	Global browse	`GET /lists/user/{userId}`	Read by ID
`public`	listed	anyone	anyone
`unlisted`	hidden	owner only	anyone holding the ID
`private`	hidden	owner and collaborators	owner and collaborators, else `403 private_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"

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

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

Hide child attributes

lists.user.id

integer

required

The owner's Simkl user ID.

Example:

5

lists.user.name

string

required

The owner's display name.

Example:

"SIMKL"

lists.user.avatar

string

required

Absolute URL to the owner's avatar at 100px. Users with no avatar of their own get the shared placeholder.

Example:

"https://simkl.in/avatars/5/5_100.jpg?1682980938"

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

Hide child attributes

lists.counts.items

integer

required

Titles in the list.

Example:

222

lists.counts.likes

integer

required

Likes the list has received.

Example:

95

lists.counts.followers

integer

required

Users following the list.

Example:

104

lists.counts.comments

integer

required

Comments on the list.

Example:

0

lists.counts.collaborators

integer

required

Users who can edit the list besides the owner.

Example:

1

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

Hide child attributes

lists.top_items.id

integer

required

Simkl ID of the title.

Example:

50250

lists.top_items.type

enum<string>

required

Media type of this title.

Available options:

movie,

tv,

anime

Example:

"anime"

lists.top_items.poster

string

required

Poster path -- see Images for how to turn it into a URL. Never null here: an item with no poster on file is skipped rather than returned with an empty one, so every entry in top_items is renderable.

Example:

"83/83063509ab6ef28d2"

lists.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:

["position", "asc"]

lists.updated_at

string<date-time>

required

When the list was last modified, UTC.

Example:

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

lists.created_at

string<date-time>

required

When the list was created, UTC.

Example:

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

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

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Custom Lists

Search

TV

Anime

Movies

Ratings

Users

Changes

Get a user's custom lists

Requires a PRO or VIP account

Sorting

Authorizations

Path Parameters

Query Parameters

Response