> ## Documentation Index > Fetch the complete documentation index at: https://api.simkl.org/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```json { "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. ## OpenAPI ````yaml /openapi.json get /lists/user/{userId} openapi: 3.1.0 info: title: Simkl API version: 1.0.0 description: >- The **Simkl API** lets you build apps that track Movies, TV Shows, and Anime — scrobble playback, sync watch history, and pull rich metadata. All requests use HTTPS and return JSON. The base URL is `https://api.simkl.com`. **Every request needs three URL parameters and a `User-Agent` header:** ``` /endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app&app-version=1.0 ``` See [Headers and required parameters](/conventions/headers) for the full reference. Endpoints that read or modify a user's data also need an `Authorization: Bearer ` header — see [OAuth 2.0](/api-reference/oauth) or the [PIN flow](/api-reference/pin). > ⚠️ **About the auto-rendered cURL examples on each endpoint page:** they omit `?client_id=…&app-name=…&app-version=…` from the URL for brevity. **You must add them yourself when copy-pasting**, or use the interactive **"Try it"** playground (it fills them in for you). This is a Mintlify rendering convention — every Mintlify-built API doc behaves the same way. **Get started** - [Quickstart](/quickstart) — first request in 60 seconds - [API rules](/api-rules) — what's allowed, what isn't - [Standard media objects](/conventions/standard-media-objects) — the shapes every endpoint speaks - [Errors](/conventions/errors) — every status code Simkl returns contact: name: Simkl Developer Support url: https://support.simkl.com termsOfService: https://simkl.com/about/policies/terms/ license: name: Simkl API Terms of Use url: https://simkl.com/about/policies/terms/ x-logo: url: https://i.simkl.com/img_tv/apiary_logo_api.png backgroundColor: '#0E5DAB' altText: Simkl servers: - url: https://api.simkl.com description: Production API - url: https://data.simkl.in description: CDN for static, public data files (Calendar + Trending). No auth required. security: - clientId: [] - simklApiKey: [] tags: - name: OAuth V2 description: >- Standards-compliant OAuth 2.0 with PKCE, scopes and refresh tokens. The recommended way to authenticate new apps. - name: OAuth 2.0 description: >- OAuth 2.0 authorization-code flow for web and mobile apps. The user is redirected to Simkl, signs in, approves your app, and is redirected back with a `code` you exchange for an `access_token`. Long-lived tokens — no refresh-token flow needed. externalDocs: description: OAuth 2.0 walkthrough url: https://api.simkl.org/api-reference/oauth - name: PIN description: >- Device flow for TVs, consoles, smart watches, CLI tools — anywhere typing a URL is hard. Show a 5-character code; user enters it on simkl.com/pin; you poll for the access token. **No `client_secret` required.** externalDocs: description: PIN flow walkthrough url: https://api.simkl.org/api-reference/pin - name: Redirect description: >- Helper redirects for one-click "mark as watched", trailers, sharing, and more. - name: Search description: Find shows, movies, and anime by ID, text query, file name, or randomly. externalDocs: description: Search guide url: https://api.simkl.org/guides/search - name: Movies description: >- Browse the Simkl movies catalog: details, premieres, top-of-best, and genre filters. - name: TV description: >- Browse the Simkl TV catalog: details, episodes, what's airing, premieres, top-of-best, and genre filters. - name: Anime description: >- Browse the Simkl anime catalog: details, episodes, what's airing, premieres, top-of-best, and genre filters. - name: Ratings description: >- Read Simkl's average community rating, rank, drop rate, and external ratings (IMDB, MAL) for any item, or for every item in a user's lists. - name: Scrobble description: >- Report real-time playback to Simkl with `start`, `pause`, and `stop`. At ≥ 80 % progress Simkl marks the item as watched automatically; below 80 % the session is saved as a paused playback the user can resume from any device. See [Standard media objects](/conventions/standard-media-objects) for the supported ID keys. ### Supported ID keys Inside any `ids` object, pass as many of these as you have. Simkl resolves to the canonical record. | ID key | Type | Example | |---|---|---| | `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. | | `imdb` | string | `tt1520211` | | `tmdb` | integer | `76757` (for TV, specify `type`) | | `tvdb` | int / string | `153021` or `the-walking-dead` | | `mal` | integer | `4246` (MyAnimeList) | | `anidb` | integer | `10846`. Specifying just this is enough for anime lookups. | | `anilist` | integer | `21` | | `kitsu` | integer | `12` | | `anisearch` | integer | `2227` | | `animeplanet` | string | `one-piece` | | `livechart` | integer | `321` | | `letterboxd` | string | `the-truman-show` | | `netflix` | integer | `70210890` (movie ID) | | `traktslug` | string | `john-wick-chapter-4-2023` | > 📖 Full reference: [Standard media objects](/conventions/standard-media-objects) externalDocs: description: Scrobble guide url: https://api.simkl.org/guides/scrobble - name: Sync description: >- Use Simkl as a cloud backup for the user's watch history and lists (Watching, Plan to Watch, On Hold, Dropped, Completed). **Always check [`/sync/activities`](/api-reference/simkl/get-activities) first** and sync only the lists that have moved. All write endpoints accept arrays — batch aggressively. See [Standard media objects](/conventions/standard-media-objects) for the supported ID keys. ### Supported ID keys Inside any `ids` object, pass as many of these as you have. Simkl resolves to the canonical record. | ID key | Type | Example | |---|---|---| | `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. | | `imdb` | string | `tt1520211` | | `tmdb` | integer | `76757` (for TV, specify `type`) | | `tvdb` | int / string | `153021` or `the-walking-dead` | | `mal` | integer | `4246` (MyAnimeList) | | `anidb` | integer | `10846`. Specifying just this is enough for anime lookups. | | `anilist` | integer | `21` | | `kitsu` | integer | `12` | | `anisearch` | integer | `2227` | | `animeplanet` | string | `one-piece` | | `livechart` | integer | `321` | | `letterboxd` | string | `the-truman-show` | | `netflix` | integer | `70210890` (movie ID) | | `traktslug` | string | `john-wick-chapter-4-2023` | > 📖 Full reference: [Standard media objects](/conventions/standard-media-objects) externalDocs: description: Sync guide url: https://api.simkl.org/guides/sync - name: Users description: User profile, settings, and watch statistics. - name: Lists description: >- Custom lists, read-only and in beta. Requires a Simkl PRO or VIP access token. externalDocs: description: Simkl API documentation url: https://api.simkl.org paths: /lists/user/{userId}: get: tags: - Lists summary: Get a user's custom lists description: >- 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: ```json { "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. operationId: get-user-lists parameters: - name: userId in: path required: true schema: type: integer description: Numeric Simkl user ID. - name: limit in: query required: false schema: type: integer default: 50 minimum: 1 maximum: 500 description: >- 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`. - name: page in: query required: false schema: type: integer default: 1 minimum: 1 description: >- 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. - name: direction in: query required: false schema: type: string enum: - asc - desc description: Sort direction. Anything other than `asc` or `desc` is a `400`. - name: sort in: query required: false schema: type: string default: updated enum: - updated - created - name - likes - followers - items - popularity description: Ordering. Anything outside this set is a `400`. - name: followed in: query required: false schema: type: string enum: - 'true' description: >- Set to the literal string `true` to include lists the user follows. `1`, `yes` and `on` do nothing. - name: collaborants in: query required: false schema: type: string enum: - 'true' description: >- Set to the literal string `true` to include lists the user collaborates on. Only meaningful when viewing your own account. responses: '200': description: >- The user's lists. This route has no PRO or VIP gate -- unlike `GET /lists/{id}`, an anonymous caller gets the real payload. content: application/json: schema: type: object description: Pagination plus the `lists` array. required: - pagination - lists properties: pagination: $ref: '#/components/schemas/CustomListPagination' lists: type: array items: $ref: '#/components/schemas/CustomList' description: >- One entry per list. Reading your own library adds a `pinned` flag to every entry, including followed and collaborated ones. examples: lists: summary: Own library, including a followed list value: 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 '400': description: >- A query parameter failed validation, including an unrecognised `sort`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: wrong_parameter code: 400 message: Invalid sort parameter '404': description: No such user. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: url_failed code: 404 message: User not found security: - bearerAuth: [] components: schemas: CustomListPagination: type: object required: - page - limit - total_items - total_pages properties: page: type: integer description: The page actually returned, after clamping. limit: type: integer description: The page size actually used, after clamping. total_items: type: integer description: Total matching items. total_pages: type: integer description: >- Total pages at this `limit`. Remember the `page` times `limit` cap of 10000 -- this can report more pages than you are allowed to reach. CustomList: type: object description: >- A custom list's metadata. Returned on its own inside `lists[]` by `GET /lists/user/{userId}`, and merged alongside `pagination` and `items` by `GET /lists/{id}`. required: - id - name - slug - description - media_type - type - privacy - display_number - user - counts - top_items - sort - updated_at - created_at properties: id: type: integer description: Numeric list ID -- the value to pass to `GET /lists/{id}`. example: 216282 name: type: string description: The list's title. example: Regular TV list slug: type: string description: >- URL-safe form of the name, for building a link to the list on simkl.com. example: regular-tv-list description: $ref: '#/components/schemas/CustomListDescription' media_type: type: string enum: - movies - tv - anime - manga - characters - companies description: >- 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. example: tv type: type: string enum: - regular - auto - favorite - voting - tier - import - recommendations description: >- 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. example: regular privacy: type: string enum: - public - unlisted - private description: >- 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. example: public display_number: type: boolean description: >- 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: $ref: '#/components/schemas/CustomListUser' counts: $ref: '#/components/schemas/CustomListCounts' top_items: type: array description: >- 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. items: $ref: '#/components/schemas/CustomListTopItem' maxItems: 5 sort: type: array description: >- 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. minItems: 2 maxItems: 2 items: type: string example: - position - asc updated_at: type: string format: date-time description: When the list was last modified, UTC. example: '2026-08-27T23:49:29Z' created_at: type: string format: date-time description: When the list was created, UTC. example: '2025-02-03T14:41:56Z' pinned: type: boolean description: >- 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](/conventions/null-values). example: false ErrorResponse: type: object description: >- Standard error envelope for 4xx and 5xx responses. Branch on `error` (machine-readable identifier) — `message`, when present, is human-readable guidance and is **not stable across releases**. properties: error: type: string description: >- Machine-readable error identifier. Stable across responses — use this for programmatic branching in client code. Examples: `user_token_failed`, `client_id_failed`, `empty_field`, `wrong_parameter`, `id_err`, `rate_limit`. example: user_token_failed code: type: integer description: >- HTTP status code echoed in the body for convenience — same value as the response status line. Always an integer. example: 401 message: type: string description: >- Human-readable error guidance. Optional — present on most errors, but not guaranteed. May reference the specific field or value that triggered the error. NOT stable; do not parse. example: Your client_id is wrong. Try another one required: - error - code CustomListDescription: type: object description: >- The list's blurb, in two lengths. Both are independently optional -- a list can have a short description and no full one, or neither. required: - short - full properties: short: type: - string - 'null' description: >- Type 4 null -- the owner has not written a short description. See [Null and missing values](/conventions/null-values). example: >- Some anime entertain. These ones break your brain, reconstruct it, then break it again. full: type: - string - 'null' description: >- Type 4 null -- the owner has not written a full description. See [Null and missing values](/conventions/null-values). May contain newlines. example: >- Ever watched an anime that left you staring at the screen in shock? From psychological labyrinths to existential nightmares, these anime are designed to mess with your mind. CustomListUser: type: object description: >- 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. required: - id - name - avatar properties: id: type: integer description: The owner's Simkl user ID. example: 5 name: type: string description: The owner's display name. example: SIMKL avatar: type: string description: >- 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 CustomListCounts: type: object description: >- 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. required: - items - likes - followers - comments - collaborators properties: items: type: integer description: Titles in the list. example: 222 likes: type: integer description: Likes the list has received. example: 95 followers: type: integer description: Users following the list. example: 104 comments: type: integer description: Comments on the list. example: 0 collaborators: type: integer description: Users who can edit the list besides the owner. example: 1 CustomListTopItem: type: object description: >- A poster-only preview entry, enough to render a list card without fetching the list itself. required: - id - type - poster properties: id: type: integer description: Simkl ID of the title. example: 50250 type: type: string enum: - movie - tv - anime description: Media type of this title. example: anime poster: type: string description: >- Poster path -- see [Images](/conventions/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 securitySchemes: clientId: type: apiKey in: query name: client_id description: >- Preferred form: your `client_id` as a URL query parameter on every request. Self-describing in logs and curl commands. See [Headers and required parameters](/conventions/headers). x-default: YOUR_CLIENT_ID simklApiKey: type: apiKey in: header name: simkl-api-key description: >- Optional alias for the `client_id` query parameter. Simkl accepts your `client_id` either as the `simkl-api-key` request header **or** as the `?client_id=…` query parameter — pick one. The query-parameter form is preferred because it makes the request fully self-describing in URL form. x-default: YOUR_CLIENT_ID bearerAuth: type: http scheme: bearer description: >- 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](/api-reference/auth). x-default: YOUR_ACCESS_TOKEN ````