> ## 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 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: ```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. ### 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. ## OpenAPI ````yaml /openapi.json get /lists/{id} 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/{id}: get: tags: - Lists summary: Get a custom list description: >- 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: ```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. ### 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. operationId: get-list parameters: - name: id in: path required: true schema: type: integer description: Numeric list 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 description: >- 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. - name: extended in: query required: false schema: type: string enum: - full description: '`full` adds an `overview` field to every item.' responses: '200': description: >- The list, **or** a `premium_only` body if the caller is not PRO or VIP. Both are 200 -- check for an `error` key. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CustomList' - type: object required: - pagination - items properties: pagination: $ref: '#/components/schemas/CustomListPagination' items: type: array items: $ref: '#/components/schemas/CustomListItem' description: This page of the list's titles. description: >- The list's metadata, merged with `pagination` and this page of `items`. Note `top_items` is always empty here. - $ref: '#/components/schemas/CustomListPremiumOnly' examples: list: summary: PRO or VIP caller value: id: 216324 name: Unlisted TV list slug: unlisted-tv-list description: short: null full: null media_type: tv type: regular privacy: unlisted display_number: true user: id: 8199460 name: testweek avatar: https://us.simkl.in/img_tv/ico_profile_guest.png counts: items: 3 likes: 0 followers: 0 comments: 0 collaborators: 0 top_items: [] sort: - position - asc updated_at: '2026-09-16T05:47:25Z' created_at: '2026-09-16T05:43:39Z' pagination: page: 1 limit: 50 total_items: 3 total_pages: 1 items: - note: {} title: Stranger Things year: 2016 type: tv poster: 18/1886552367968d91bc fanart: 48/48131003734eec969 runtime: 2725 ids: simkl_id: 548312 slug: stranger-things imdb: tt4574334 tmdb: '66732' tvdb: '305288' tvdbslug: stranger-things traktslug: stranger-things rank: 293 position: 1 ratings: simkl: rating: 8.21 votes: 12117 drop_rate: 3.5% imdb: rating: 8.6 votes: 1738548 watched: 98416 plan_to_watch: 13779 watching: 57484 completed: 40981 hold: 1431 dropped: 3611 status: ended release_date: '2016-07-16T00:00:00Z' genres: - Adventure - Drama - Fantasy - Horror - Mystery - Science-Fiction - Suspense - Thriller origin_countries: - us original_language: en metadata: 2016 - 2026 • Netflix • 42 episodes year_start_end: 2016 - 2026 total_episodes: 42 runtime_episode: 78 network: Netflix next_episode_date: null total_seasons: 5 premium_only: summary: Free or anonymous caller (HTTP 200) value: 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 '400': description: A query parameter failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: wrong_parameter code: 400 message: Invalid limit parameter '403': description: >- A private list the caller is not the owner of or a collaborator on. The body carries no message. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: private_list code: 403 '404': description: No such list. Only reachable with a PRO or VIP token -- see above. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: url_failed code: 404 message: List not found security: - bearerAuth: [] components: schemas: 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 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. CustomListItem: type: object description: >- One title in a custom list. The fields below the base set are appended by media type, so a movie entry and a TV entry are not the same shape. Because a list holds a single media type, every item in one response carries the same shape as its siblings -- branch on the list's `media_type` once rather than per item. required: - note - title - year - type - poster - fanart - runtime - ids - rank - position - ratings - watched - plan_to_watch - watching - completed - hold - dropped - status - release_date - genres - origin_countries - original_language - metadata properties: note: type: object description: >- The owner's note on this entry. An empty object `{}` when no note has been published -- it is never `null`, so test for the `note.public` key rather than for the object itself. properties: public: type: string description: The note text. Newlines are preserved. example: Watch this one twice. title: type: string description: The title, in the language the list owner sees. example: Steins;Gate year: type: - integer - 'null' description: >- Type 4 null -- no release year is on file. See [Null and missing values](/conventions/null-values). example: 2011 type: type: string enum: - movie - tv - anime description: Media type of this title. example: anime poster: type: - string - 'null' description: >- Type 4 null -- no poster is on file. See [Null and missing values](/conventions/null-values). See [Images](/conventions/images). example: 18/18635960737bf604d4 fanart: type: - string - 'null' description: >- Type 4 null -- no backdrop is on file. See [Null and missing values](/conventions/null-values). See [Images](/conventions/images). example: 22/2233079ee2e5e77f1 runtime: type: - integer - 'null' description: >- Total runtime of the whole title in minutes -- every episode for a series, the film's length for a movie. For per-episode length see `runtime_episode`. Type 4 null -- no runtime is on file. See [Null and missing values](/conventions/null-values). example: 1488 ids: type: object description: >- Identifiers for this title. `simkl_id` is always present; which external IDs appear depends on what Simkl has mapped. Only `simkl_id` is an integer -- every other identifier is a string. See [IDs](/conventions/standard-media-objects). required: - simkl_id - slug properties: simkl_id: type: integer description: Simkl's own ID. example: 38636 slug: type: string description: URL slug for the title's simkl.com page. example: steins-gate additionalProperties: true rank: type: - integer - 'null' description: >- Type 4 null -- the list does not carry a rank for this entry. See [Null and missing values](/conventions/null-values). example: 1 position: type: integer description: >- The entry's place in the list's own ordering, 1-based. Stable regardless of how you sort the response. example: 1 ratings: type: object description: >- Scores from Simkl plus one external source. The second key is **`mal` on an anime list and `imdb` on a movie or TV list** -- it is not both, so pick it from the list's `media_type`. required: - simkl properties: simkl: type: object required: - rating - votes - drop_rate properties: rating: type: - number - 'null' description: >- Type 4 null -- the title has no Simkl score yet. See [Null and missing values](/conventions/null-values). example: 9.1 votes: type: - integer - 'null' description: >- Type 4 null -- the title has no Simkl votes yet. See [Null and missing values](/conventions/null-values). example: 4210 drop_rate: type: - string - 'null' description: >- Share of users who dropped this title, as a preformatted percentage string such as `"12.5%"` -- not a number. Type 4 null -- there is not enough data to compute a drop rate. See [Null and missing values](/conventions/null-values). example: 3.2% imdb: type: object required: - rating - votes properties: rating: type: - number - 'null' description: >- Type 4 null -- the title has no score yet. See [Null and missing values](/conventions/null-values). example: 8.4 votes: type: - integer - 'null' description: >- Type 4 null -- the title has no votes yet. See [Null and missing values](/conventions/null-values). example: 15832 mal: type: object required: - rating - votes properties: rating: type: - number - 'null' description: >- Type 4 null -- the title has no score yet. See [Null and missing values](/conventions/null-values). example: 8.4 votes: type: - integer - 'null' description: >- Type 4 null -- the title has no votes yet. See [Null and missing values](/conventions/null-values). example: 15832 watched: type: integer description: Users who have watched this title. example: 51204 plan_to_watch: type: integer description: Users who plan to watch it. example: 18330 watching: type: integer description: Users currently watching it. example: 2210 completed: type: integer description: Users who completed it. example: 40118 hold: type: integer description: Users who have it on hold. example: 1902 dropped: type: integer description: Users who dropped it. example: 1633 status: type: string description: >- Release status, e.g. `ended`, `returning series`, `ongoing`, `released`, `canceled`, `planned`. example: ended release_date: type: - string - 'null' format: date-time description: >- First release, as a full UTC timestamp rather than a bare date -- the time component is usually `00:00:00Z` but is not guaranteed to be. Type 4 null -- no release date is on file. See [Null and missing values](/conventions/null-values). example: '2016-07-16T00:00:00Z' genres: type: array items: type: string description: Genre names. Empty array when none are on file. example: - Sci-Fi - Thriller origin_countries: type: array items: type: string description: >- Lowercased country codes. Simkl stores a single country today; this is an array so that can grow without a breaking change. Empty when none is on file. example: - jp original_language: type: - string - 'null' description: >- Type 4 null -- no original language is on file. See [Null and missing values](/conventions/null-values). Lowercased when present. example: ja metadata: type: - string - 'null' description: >- Preformatted summary line Simkl renders on the title's card, with parts separated by ` • `. Display-only -- parse the individual fields instead of splitting this. Type 4 null -- there is nothing to summarise. See [Null and missing values](/conventions/null-values). example: 2016 - 2026 • Netflix • 42 episodes overview: type: - string - 'null' description: >- Synopsis. **Only present when you pass `extended=full`.** Type 4 null -- no synopsis is on file. See [Null and missing values](/conventions/null-values). example: >- When a young boy vanishes, a small town uncovers a mystery involving secret experiments. year_start_end: type: - string - 'null' description: >- Display range, spaced around the dash as `2016 - 2026`. Series only -- absent on movies. Type 4 null -- no range is on file. See [Null and missing values](/conventions/null-values). example: 2016 - 2026 total_episodes: type: integer description: Episodes on file. Series only -- absent on movies. example: 24 runtime_episode: type: - integer - 'null' description: >- Per-episode runtime in minutes. Series only -- absent on movies. Type 4 null -- no per-episode runtime is on file. See [Null and missing values](/conventions/null-values). example: 24 network: type: - string - 'null' description: >- Originating network. Series only -- absent on movies. Type 4 null -- no network is on file. See [Null and missing values](/conventions/null-values). example: TV Tokyo next_episode_date: type: - string - 'null' format: date-time description: >- Air date of the next episode, as a full UTC timestamp. Series only -- absent on movies. Type 4 null -- nothing is scheduled, which includes every finished series. See [Null and missing values](/conventions/null-values). example: null total_seasons: type: integer description: >- Seasons on file. **TV only** -- absent on movies and on anime, which uses `mapped_tvdb_seasons` instead. example: 5 budget: type: - integer - 'null' description: >- Production budget in USD. **Movies only.** Type 4 null -- no budget is on file. See [Null and missing values](/conventions/null-values). example: 20000000 box_office: type: - integer - 'null' description: >- Worldwide revenue in USD. **Movies only.** Type 4 null -- no revenue is on file. See [Null and missing values](/conventions/null-values). example: 121463226 dvd_date: type: - string - 'null' format: date-time description: >- Home-release date, as a full UTC timestamp. **Movies only.** Type 4 null -- no home-release date is on file. See [Null and missing values](/conventions/null-values). example: '2007-08-26T04:00:00Z' anime_type: type: string description: >- Anime subtype, lowercased, e.g. `tv`, `movie`, `ova`, `ona`, `special`. **Anime only.** example: tv mapped_tvdb_seasons: type: array items: type: integer description: >- TVDB seasons this anime maps onto. **Anime only.** Empty when the title has no TVDB series ID; `[1]` when it has one but no finer mapping. A long-running series can map onto many -- One Piece returns 23. example: - 1 - 2 - 3 CustomListPremiumOnly: type: object description: >- Returned with **HTTP 200** when the caller is not PRO or VIP. Carries no list data. Check for the `error` key before reading `items`. required: - error - message - item properties: error: type: string enum: - premium_only description: Always the lowercase string `premium_only`. message: type: string description: Human-readable explanation. item: type: object description: >- A single renderable placeholder, not a list item. Display it in place of the list so the user sees an explanation rather than an empty screen. properties: title: type: string description: type: string poster: type: string description: Absolute URL, ready to display. 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 ````