> ## 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 all items of one type in one status bucket > > ## ⚠️ For continuous sync, do NOT call `/sync/all-items` on a timer > > The correct loop, every time you want to check for changes: > > 1. **Call [`GET /sync/activities`](/api-reference/simkl/get-activities) first.** It returns a tiny JSON of `last-modified` timestamps per category — costs almost nothing. > 2. **Compare them with the snapshot you saved last time** — the whole `/sync/activities` response. If the top-level `all` is unchanged, stop here. Do **not** call `/sync/all-items`. > 3. **Only if a watchlist timestamp changed**, call `/sync/all-items?date_from=`, passed exactly as returned. The `date_from` makes the server return only the small delta of items that changed strictly after that moment, not the user's entire library. > 4. **Save the new `/sync/activities` response as your snapshot** — only after every fetch has succeeded. > > Polling `/sync/all-items` directly on a timer (without checking `/sync/activities` and without `date_from`) downloads the user's whole library every call. It overloads the API server and hurts every other client. > > **Apps that do this will have their `client_id` suspended.** No warning, no appeal — we see the traffic pattern and turn the key off. > > Read the [**Sync guide**](/guides/sync) end-to-end before shipping anything that calls this endpoint. The full two-phase model (initial full sync → activities-checked delta loop) is documented there with reference implementations in Node and Python. The two-phase model (initial pull → activities-checked delta loop), `date_from` semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python. **Required reading** before shipping anything that polls this endpoint. Session lifecycle (`active` / `completed` / `closed`), per-item rewatch fields, episode-level tracking, flag combinations for reading sessions back, and ready-made code for the UI patterns simkl.com uses on every detail page. Required if you set `?allow_rewatch=yes`. The single endpoint that powers watchlist reads. Both `{type}` and `{status}` are optional path segments, and any combination is valid: | Path | Returns | | --- | --- | | `/sync/all-items` | Every type, every status. The full library. | | `/sync/all-items/{type}` | A single type (`shows`, `movies`, or `anime`), every status. | | `/sync/all-items/{type}/{status}` | One type, one status bucket. | The response shape is the same across all three forms: a top-level object keyed by `shows`, `movies`, and `anime`. Filtered calls just include fewer top-level keys; an empty result returns `{}`. See [Per-endpoint shape matrix](/conventions/null-values#per-endpoint-shape-matrix). Pair this endpoint with [`GET /sync/activities`](/api-reference/simkl/get-activities) and the `date_from` query parameter for incremental sync — see the [Sync guide](/guides/sync) for the two-phase model. **Watchlist statuses by type:** | Type | `watching` | `plantowatch` | `hold` | `dropped` | `completed` | |------|:-:|:-:|:-:|:-:|:-:| | `shows` | ✅ | ✅ | ✅ | ✅ | ✅ | | `anime` | ✅ | ✅ | ✅ | ✅ | ✅ | | `movies` | — | ✅ | — | ✅ | ✅ | Movies skip `watching` and `hold` — see [Watchlist statuses](/conventions/list-statuses). #### Useful query parameters A quick map of the params below — see each parameter's full schema later on this page. | Param | What it does | |---|---| | `date_from` | Required on every continuous-sync call. Returns only items whose watchlist entry changed **strictly after** this ISO-8601 timestamp — pass the top-level `all` from your saved `/sync/activities` snapshot, exactly as returned. Every row carries the item's current `user_rating`, so no separate ratings request is needed — except for a rating-only change, which does not count here: read those from [`GET /sync/ratings`](/api-reference/simkl/get-user-ratings), and only when `rated_at` moved. | | `extended=simkl_ids_only` / `=ids_only` / `=full` / `=full_anime_seasons` | Controls response richness — from just `ids.simkl` (smallest) up to per-episode breakdowns. `=full` is **required** for `seasons[].episodes[]` and is the only value that adds `runtime`; it does **not** add `overview` / `fanart` / `genres` / `ratings` (use the detail endpoints for catalog metadata). Pair `=full` and `=full_anime_seasons` with `date_from` — they're significantly larger payloads. | | `include_all_episodes=yes` / `=original` | **Requires `extended=full`** (no effect on its own). Loads `seasons[].episodes[]` for items in `completed` and `dropped` too (which skip episode load by default). `yes` fills in virtual episode rows — stamped with the show's last-watched time — where per-episode data is missing; `original` returns only the episodes the user actually recorded, which can be fewer than `watched_episodes_count` for a show marked complete in one action. If a large library returns `400 max_items`, `original` is the lighter of the two. | | `episode_watched_at=yes` | Adds per-episode `watched_at` timestamps to every loaded episode. **Requires `extended=full`** — episodes must be loaded first, so on its own it does nothing. | | `episode_tvdb_id=yes` | Adds `ids.tvdb_id` per episode. | | `next_watch_info=yes` | On `watching` items with a next episode, attaches `next_to_watch_info` (`title`, `season`, `episode`, `date`). | | `memos=yes` | Includes the user's per-item `memo` object (`text` capped at 140 chars). | | `anime_type=movies` | Restrict the `anime` results to the anime-movie subtype. `movies` is the only accepted value — it's a subtype filter, not a full type selector. (The per-item `anime_type` **response** field still carries the full vocabulary: `tv`, `movie`, `ova`, `ona`, `special`, `music video`.) | | `language=en` | Force English titles instead of the user's profile language. | | `allow_rewatch=yes` | Synthesize one extra entry per rewatch session alongside the canonical row. **Simkl PRO / VIP only** — gate the flag on `account.type` from [`GET /users/settings`](/api-reference/simkl/get-user-settings) (cache it; refetch only when `activities.settings.all` bumps — see [Rewatches guide → PRO / VIP gate](/guides/rewatches)). Free-tier callers get a silent no-op that still consumes a rate-limit slot. See the [Rewatches guide](/guides/rewatches) for the full pattern. | **Rewatches** (Simkl PRO / VIP). Without the flag, each item — movie, show, or anime — appears once in the response, reflecting the user's current watch state. Set `?allow_rewatch=yes` and any item with saved rewatch sessions appears multiple times: the normal entry, plus one extra entry per rewatch session. The extra entries carry `is_rewatch: true`, `rewatch_id`, `rewatch_status` (`active` / `completed` / `closed`), `last_watched_at`, and `watched_episodes_count`, so you can tell them apart from the main entry and from each other. #### `400 max_items` — the response would be too large This endpoint builds its whole response before sending it, and refuses a request whose response would be too large to build — in practice a very large library requested with `extended=full`, especially with `include_all_episodes=yes`: ```json { "error": "max_items", "code": 400, "message": "Too many episodes: ..." } ``` Retrying the same request gets the same `400`. Split it into one status per call (`/sync/all-items/{type}/{status}`), or use `include_all_episodes=original` instead of `=yes` — it adds only the episodes the user actually watched, not every episode of every completed show. See [If a pull returns 400 max_items](/guides/sync#max-items). **Which IDs can I send/expect?** All accepted input identifiers and the keys you'll see echoed back in responses are listed at [**Standard media objects → Supported ID keys**](/conventions/standard-media-objects#supported-id-keys). Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: `slug` is **response-only** (never send it on a request). ## OpenAPI ````yaml /openapi.json get /sync/all-items/{type}/{status} 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 (adjustable per call with `?min_progress=`) Simkl marks the item as watched automatically; below that 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: /sync/all-items/{type}/{status}: get: tags: - Sync summary: Get all items of one type in one status bucket description: >- > ## ⚠️ For continuous sync, do NOT call `/sync/all-items` on a timer > > The correct loop, every time you want to check for changes: > > 1. **Call [`GET /sync/activities`](/api-reference/simkl/get-activities) first.** It returns a tiny JSON of `last-modified` timestamps per category — costs almost nothing. > 2. **Compare them with the snapshot you saved last time** — the whole `/sync/activities` response. If the top-level `all` is unchanged, stop here. Do **not** call `/sync/all-items`. > 3. **Only if a watchlist timestamp changed**, call `/sync/all-items?date_from=`, passed exactly as returned. The `date_from` makes the server return only the small delta of items that changed strictly after that moment, not the user's entire library. > 4. **Save the new `/sync/activities` response as your snapshot** — only after every fetch has succeeded. > > Polling `/sync/all-items` directly on a timer (without checking `/sync/activities` and without `date_from`) downloads the user's whole library every call. It overloads the API server and hurts every other client. > > **Apps that do this will have their `client_id` suspended.** No warning, no appeal — we see the traffic pattern and turn the key off. > > Read the [**Sync guide**](/guides/sync) end-to-end before shipping anything that calls this endpoint. The full two-phase model (initial full sync → activities-checked delta loop) is documented there with reference implementations in Node and Python. The two-phase model (initial pull → activities-checked delta loop), `date_from` semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python. **Required reading** before shipping anything that polls this endpoint. Session lifecycle (`active` / `completed` / `closed`), per-item rewatch fields, episode-level tracking, flag combinations for reading sessions back, and ready-made code for the UI patterns simkl.com uses on every detail page. Required if you set `?allow_rewatch=yes`. The single endpoint that powers watchlist reads. Both `{type}` and `{status}` are optional path segments, and any combination is valid: | Path | Returns | | --- | --- | | `/sync/all-items` | Every type, every status. The full library. | | `/sync/all-items/{type}` | A single type (`shows`, `movies`, or `anime`), every status. | | `/sync/all-items/{type}/{status}` | One type, one status bucket. | The response shape is the same across all three forms: a top-level object keyed by `shows`, `movies`, and `anime`. Filtered calls just include fewer top-level keys; an empty result returns `{}`. See [Per-endpoint shape matrix](/conventions/null-values#per-endpoint-shape-matrix). Pair this endpoint with [`GET /sync/activities`](/api-reference/simkl/get-activities) and the `date_from` query parameter for incremental sync — see the [Sync guide](/guides/sync) for the two-phase model. **Watchlist statuses by type:** | Type | `watching` | `plantowatch` | `hold` | `dropped` | `completed` | |------|:-:|:-:|:-:|:-:|:-:| | `shows` | ✅ | ✅ | ✅ | ✅ | ✅ | | `anime` | ✅ | ✅ | ✅ | ✅ | ✅ | | `movies` | — | ✅ | — | ✅ | ✅ | Movies skip `watching` and `hold` — see [Watchlist statuses](/conventions/list-statuses). #### Useful query parameters A quick map of the params below — see each parameter's full schema later on this page. | Param | What it does | |---|---| | `date_from` | Required on every continuous-sync call. Returns only items whose watchlist entry changed **strictly after** this ISO-8601 timestamp — pass the top-level `all` from your saved `/sync/activities` snapshot, exactly as returned. Every row carries the item's current `user_rating`, so no separate ratings request is needed — except for a rating-only change, which does not count here: read those from [`GET /sync/ratings`](/api-reference/simkl/get-user-ratings), and only when `rated_at` moved. | | `extended=simkl_ids_only` / `=ids_only` / `=full` / `=full_anime_seasons` | Controls response richness — from just `ids.simkl` (smallest) up to per-episode breakdowns. `=full` is **required** for `seasons[].episodes[]` and is the only value that adds `runtime`; it does **not** add `overview` / `fanart` / `genres` / `ratings` (use the detail endpoints for catalog metadata). Pair `=full` and `=full_anime_seasons` with `date_from` — they're significantly larger payloads. | | `include_all_episodes=yes` / `=original` | **Requires `extended=full`** (no effect on its own). Loads `seasons[].episodes[]` for items in `completed` and `dropped` too (which skip episode load by default). `yes` fills in virtual episode rows — stamped with the show's last-watched time — where per-episode data is missing; `original` returns only the episodes the user actually recorded, which can be fewer than `watched_episodes_count` for a show marked complete in one action. If a large library returns `400 max_items`, `original` is the lighter of the two. | | `episode_watched_at=yes` | Adds per-episode `watched_at` timestamps to every loaded episode. **Requires `extended=full`** — episodes must be loaded first, so on its own it does nothing. | | `episode_tvdb_id=yes` | Adds `ids.tvdb_id` per episode. | | `next_watch_info=yes` | On `watching` items with a next episode, attaches `next_to_watch_info` (`title`, `season`, `episode`, `date`). | | `memos=yes` | Includes the user's per-item `memo` object (`text` capped at 140 chars). | | `anime_type=movies` | Restrict the `anime` results to the anime-movie subtype. `movies` is the only accepted value — it's a subtype filter, not a full type selector. (The per-item `anime_type` **response** field still carries the full vocabulary: `tv`, `movie`, `ova`, `ona`, `special`, `music video`.) | | `language=en` | Force English titles instead of the user's profile language. | | `allow_rewatch=yes` | Synthesize one extra entry per rewatch session alongside the canonical row. **Simkl PRO / VIP only** — gate the flag on `account.type` from [`GET /users/settings`](/api-reference/simkl/get-user-settings) (cache it; refetch only when `activities.settings.all` bumps — see [Rewatches guide → PRO / VIP gate](/guides/rewatches)). Free-tier callers get a silent no-op that still consumes a rate-limit slot. See the [Rewatches guide](/guides/rewatches) for the full pattern. | **Rewatches** (Simkl PRO / VIP). Without the flag, each item — movie, show, or anime — appears once in the response, reflecting the user's current watch state. Set `?allow_rewatch=yes` and any item with saved rewatch sessions appears multiple times: the normal entry, plus one extra entry per rewatch session. The extra entries carry `is_rewatch: true`, `rewatch_id`, `rewatch_status` (`active` / `completed` / `closed`), `last_watched_at`, and `watched_episodes_count`, so you can tell them apart from the main entry and from each other. #### `400 max_items` — the response would be too large This endpoint builds its whole response before sending it, and refuses a request whose response would be too large to build — in practice a very large library requested with `extended=full`, especially with `include_all_episodes=yes`: ```json { "error": "max_items", "code": 400, "message": "Too many episodes: ..." } ``` Retrying the same request gets the same `400`. Split it into one status per call (`/sync/all-items/{type}/{status}`), or use `include_all_episodes=original` instead of `=yes` — it adds only the episodes the user actually watched, not every episode of every completed show. See [If a pull returns 400 max_items](/guides/sync#max-items). **Which IDs can I send/expect?** All accepted input identifiers and the keys you'll see echoed back in responses are listed at [**Standard media objects → Supported ID keys**](/conventions/standard-media-objects#supported-id-keys). Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: `slug` is **response-only** (never send it on a request). operationId: get-sync-all-items-type-status parameters: - name: type in: path description: >- One of `shows`, `movies`, `anime`, or `all`. Pass `all` to skip filtering on type even when the runtime accepts the segment-less form, so for spec strictness this is `true`. To call without it in practice, just drop the segment from the URL. schema: type: string enum: - movies - shows - anime - all example: all required: true examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: all phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: all movies_completed_filtered: summary: Path filter — only completed movies value: movies watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: shows extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: shows anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: anime simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: all ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: movies rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: all all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: all - name: status in: path description: >- One of `watching`, `plantowatch`, `hold`, `completed`, `dropped`, or `all`. Movies accept only `plantowatch`, `completed`, `dropped`, and `all`; TV and anime accept all six. Pass `all` to skip filtering on status — `/sync/all-items/{type}/all` returns every status for that type. schema: $ref: '#/components/schemas/WatchlistStatus' enum: - watching - plantowatch - hold - completed - dropped - all example: all required: true examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: all phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: all movies_completed_filtered: summary: Path filter — only completed movies value: completed watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: watching extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: watching anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: completed simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: all ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: completed rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: completed all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: all - name: allow_rewatch in: query required: false schema: type: string enum: - 'yes' - 'no' default: 'no' description: >- Opt into rewatch tracking. When `yes`, `POST /sync/history` records an additional rewatch session instead of being a no-op for already-watched items, and `GET /sync/all-items` returns one extra entry per saved rewatch session alongside the item's normal entry. Available to Simkl **PRO** and **VIP** users — non-PRO callers see no effect even with the flag set. ⚠️ **Do not enable this flag until you've read the [Rewatches guide](/guides/rewatches) end-to-end and implemented the precautions.** Used carelessly (on retries, on every scrobble event, on importer re-runs, without pinning `rewatch_id` after the first write), it will pollute the user's history stats and rewatches panel with phantom sessions. The flag should be gated behind explicit user intent — a dedicated "Rewatch" button — never on background or automated flows. Also expose a per-user *Track rewatches* toggle in your app's settings (default off) — not every user wants the rewatch-session complexity. Limits: up to **50 rewatches per item** (movie, show, or anime), and any two watch events on the **same item** (movie or episode) must be at least **2 days apart** — a new rewatch within 48 hours of the previous watch of that same item collapses into the same session (it's a rewatch, not a rewind 😄). Full walkthrough — session lifecycle (`active` / `completed` / `closed` with bidirectional transitions), episode-level tracking, reading sessions back from `GET /sync/all-items`, and ready-made code for simkl.com-style UI patterns — in the [Rewatches guide](/guides/rewatches). examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'yes' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - name: date_from in: query required: false description: >- ISO-8601 timestamp. Returns only items changed **strictly after** this time — one stamped exactly at this value is not returned. Pass the top-level `all` from the `/sync/activities` response you saved as your snapshot, exactly as returned. schema: type: string format: date-time examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: '' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: '2026-05-14T00:00:00Z' movies_completed_filtered: summary: Path filter — only completed movies value: '' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: '' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: '' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: '' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: '' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: '' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: '' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: '' - name: extended in: query description: >- Controls response richness. Omit for the default (summary fields only — status, counters, `last_watched` / `next_to_watch` markers, no episode arrays). - `simkl_ids_only` — smallest payload: just `ids.simkl` per item. Ideal for the deletion-reconciliation diff in continuous sync. - `ids_only` — same, plus external IDs (`imdb`, `tmdb`, `tvdb`, `mal`, …). - `full` — **required to get the per-episode `seasons[].episodes[]` arrays**; without it, `episode_watched_at` and `include_all_episodes` do nothing. Necessary but not always sufficient: on its own it loads episodes for `watching` / `hold` / `plantowatch` items only — `completed` and `dropped` additionally need `include_all_episodes`. The only extra *metadata* field it adds is `runtime`. - `full_anime_seasons` — like `full`, plus TVDB season/episode mapping on anime (`mapped_tvdb_seasons` at the show level, a `tvdb` block per episode). **This endpoint does not return `overview`, `fanart`, `genres`, or `ratings` at any `extended` value** — it returns watch state plus a compact item stub (`title`, `poster`, `year`, `ids`, and `runtime` on `full`). For catalog metadata, call the detail endpoints ([`/movies/{id}`](/api-reference/simkl/get-movie), [`/tv/{id}`](/api-reference/simkl/get-tv-show), [`/anime/{id}`](/api-reference/simkl/get-anime)). Large payload on `full` / `full_anime_seasons` — pair with `date_from` for continuous sync. The one expected full-library use is a one-time episode baseline on first sync (see the [Sync guide → Phase 1](/guides/sync#phase-1-initial-sync)). schema: type: string enum: - full - full_anime_seasons - simkl_ids_only - ids_only examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: full movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: full anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: full_anime_seasons simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: simkl_ids_only ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: ids_only rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: full all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: full_anime_seasons - name: next_watch_info in: query required: false schema: type: string enum: - 'yes' description: >- When `yes`, attaches a `next_to_watch_info` object to each watched item, indicating the next episode to watch. examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'yes' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - name: episode_tvdb_id in: query required: false schema: type: string enum: - 'yes' description: >- When `yes`, includes TVDB IDs on each episode in episode-bearing responses. examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - name: episode_runtime in: query required: false schema: type: string enum: - 'yes' description: >- When `yes`, adds `runtime` (whole minutes, or `null` when unknown) to each episode row. Like the other episode modifiers it needs `extended=full`, since episode rows are not loaded without it. examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'yes' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - $ref: '#/components/parameters/AllItemsLanguageQuery' - $ref: '#/components/parameters/AllItemsAnimeTypeQuery' - name: episode_watched_at in: query description: >- `yes` adds per-episode `watched_at` timestamps to every loaded episode. **Requires `extended=full`** (or `extended=full_anime_seasons`) — it's a modifier on already-loaded episodes, so on its own it does nothing. To also cover `completed` / `dropped` items, combine with `include_all_episodes` (which itself also requires `extended=full`). Pair with `date_from` for continuous sync — significantly larger response. schema: type: string const: 'yes' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'yes' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'yes' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'yes' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - name: include_all_episodes in: query description: >- Three-value flag that controls per-episode loading on canonical entries. **Requires `extended=full`** — it has no effect on its own. - `no` *(default)* — Episode lists are loaded only for items in `watching`, `plantowatch`, and `hold` statuses. Items in `completed` and `dropped` skip episode loading entirely (you get only `watched_episodes_count`). - `yes` — Load episode lists for **every** status. For completed entries with no per-episode data recorded, synthesizes virtual episode rows stamped with the item's last-watched time (the same timestamp is shared across all synthesized rows). Complete coverage, approximate dates. - `original` — Load episode lists for every status, but **skip** virtual-episode synthesis. Completed entries get only their real recorded rows with real dates — which can be **fewer** than `watched_episodes_count` for an item the user marked complete in a single action. Treat the count as authoritative for how many episodes are watched, and the rows for which ones and when. Independent of `allow_rewatch=yes` — combine the two when you need both canonical episode lists AND rewatch session episode lists in one response. Pair with `date_from` for continuous sync since the response can be much larger when episodes load for completed-bucket items. schema: type: string enum: - 'yes' - original - 'no' default: 'no' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - name: memos in: query description: >- `yes` includes the user's per-item `memo` object (`text` capped at 140 chars, plus `is_private`) in addition to all other data. Field name is singular `memo`; empty memos render as `{}`. schema: type: string const: 'yes' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. value: 'yes' - $ref: '#/components/parameters/ClientIdQuery' - $ref: '#/components/parameters/AppNameQuery' - $ref: '#/components/parameters/AppVersionQuery' - $ref: '#/components/parameters/UserAgentHeader' responses: '200': description: >- Top-level dict keyed by `shows`, `movies`, and `anime`. **Keys are present only when there's at least one item in that bucket** — filtered calls (`/movies/completed`) return just that key; an empty library returns `{}`. The per-item shape is `AllItemsEntry` — its fields are gated on the query parameters (`extended`, `memos`, `next_watch_info`, `episode_watched_at`, `episode_tvdb_id`, `allow_rewatch`, etc.). See the schema and the examples below for what each modifier adds. **To show only what the user still has to watch**, filter `watching` entries on `next_to_watch` rather than on the episode counts — [Hide shows the user is caught up on](/guides/sync#hide-caught-up-shows) explains why the arithmetic version keeps showing shows the user has finished. headers: {} content: application/json: schema: $ref: '#/components/schemas/AllItemsResponse' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) description: 'Call: `GET /sync/all-items`' value: shows: - added_to_watchlist_at: '2018-02-24T23:55:13Z' last_watched_at: null user_rated_at: null user_rating: null status: plantowatch last_watched: null next_to_watch: S01E01 watched_episodes_count: 0 total_episodes_count: 178 not_aired_episodes_count: 0 show: title: Charmed poster: 24/24273cee77f9d9f year: 1998 ids: simkl: 297 slug: charmed imdb: tt0158552 tvdb: '70626' tmdb: '1981' anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' anime_type: tv phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) description: >- Call: `GET /sync/all-items?date_from=2026-05-14T00:00:00Z&extended=full&episode_watched_at=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:35:15Z' last_watched_at: '2026-05-15T00:35:15Z' user_rated_at: null user_rating: null status: watching last_watched: S01E01 next_to_watch: null watched_episodes_count: 176 total_episodes_count: 177 not_aired_episodes_count: 0 show: title: The Walking Dead poster: 16/16913426086fc13 year: 2010 ids: simkl: 2090 slug: the-walking-dead imdb: tt1520211 tvdb: '153021' anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anime_type: tv movies: - added_to_watchlist_at: '2026-05-14T06:49:56Z' last_watched_at: null user_rated_at: null user_rating: null status: dropped watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: Pulp Fiction poster: 13/13311405613660dcc9 year: 1994 ids: simkl: 54130 slug: pulp-fiction imdb: tt0110912 movies_completed_filtered: summary: Path filter — only completed movies description: 'Call: `GET /sync/all-items/movies/completed`' value: movies: - added_to_watchlist_at: '2026-04-10T20:13:02Z' last_watched_at: '1994-09-01T16:00:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' watching_with_next_to_watch_info: summary: >- next_watch_info=yes — adds next_to_watch_info for watching items description: >- Call: `GET /sync/all-items/shows/watching?next_watch_info=yes` value: shows: - added_to_watchlist_at: '2014-11-12T18:42:53Z' last_watched_at: '2026-05-04T19:40:59Z' user_rated_at: null user_rating: null status: watching last_watched: S08E02 next_to_watch: S08E03 watched_episodes_count: 126 total_episodes_count: 165 not_aired_episodes_count: 11 show: title: Futurama poster: 18/18421459bbf0f06beb year: 1999 ids: simkl: 3407 slug: futurama imdb: tt0149460 tvdb: '73871' next_to_watch_info: title: How the West Was 1010001 season: 8 episode: 3 date: '2023-08-07T00:00:00-05:00' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes + episode_runtime=yes — per-episode watched_at and runtime description: >- Call: `GET /sync/all-items/shows/watching?extended=full&episode_watched_at=yes&episode_runtime=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:35:15Z' last_watched_at: '2026-05-15T00:35:15Z' user_rated_at: null user_rating: null status: watching last_watched: S01E01 next_to_watch: null watched_episodes_count: 176 total_episodes_count: 177 not_aired_episodes_count: 0 show: title: The Walking Dead poster: 16/16913426086fc13 year: 2010 runtime: 43 ids: simkl: 2090 slug: the-walking-dead imdb: tt1520211 tvdb: '153021' seasons: - number: 1 episodes: - number: 2 watched_at: '2026-05-15T00:32:20Z' runtime: 44 - number: 3 watched_at: '2026-05-15T00:32:21Z' runtime: 45 anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons description: >- Call: `GET /sync/all-items/anime/completed?extended=full_anime_seasons` value: anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anime_type: tv mapped_tvdb_seasons: - 1 simkl_ids_only_minimal: summary: >- extended=simkl_ids_only — smallest payload (incremental sync) description: 'Call: `GET /sync/all-items?extended=simkl_ids_only`' value: shows: - show: ids: simkl: 297 slug: charmed anime: - show: ids: simkl: 37089 slug: cowboy-bebop movies: - movie: ids: simkl: 53434 slug: the-godfather ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata description: >- Call: `GET /sync/all-items/movies/completed?extended=ids_only` value: movies: - movie: ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl PRO / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. description: >- Call: `GET /sync/all-items/all/completed?allow_rewatch=yes&extended=full&episode_watched_at=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:13:18Z' last_watched_at: '2026-05-15T00:13:18Z' user_rated_at: '2026-05-16T14:20:16Z' user_rating: 10 status: completed last_watched: null next_to_watch: null watched_episodes_count: 73 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' is_rewatch: false - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T20:00:00Z' user_rated_at: '2026-05-16T14:20:16Z' user_rating: 10 status: completed last_watched: S01E04 next_to_watch: null watched_episodes_count: 4 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' is_rewatch: true rewatch_id: 7482 rewatch_status: completed seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' - number: 2 watched_at: '2026-05-16T14:02:10Z' - number: 3 watched_at: '2026-05-16T19:00:00Z' - number: 4 watched_at: '2026-05-16T20:00:00Z' anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' anime_type: tv is_rewatch: false - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T14:02:10Z' user_rated_at: null user_rating: null status: completed last_watched: E2 next_to_watch: null watched_episodes_count: 2 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' anime_type: tv is_rewatch: true rewatch_id: 7484 rewatch_status: active seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' - number: 2 watched_at: '2026-05-16T14:02:10Z' movies: - added_to_watchlist_at: '2026-04-10T20:13:02Z' last_watched_at: '1994-09-01T16:00:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' is_rewatch: false - added_to_watchlist_at: '2026-04-11T11:44:27Z' last_watched_at: '2026-04-11T11:30:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' is_rewatch: true rewatch_id: 2368 rewatch_status: completed all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + PRO-only fields. Use it to see every possible response field in one place. description: >- Call: `GET /sync/all-items?extended=full_anime_seasons&memos=yes&next_watch_info=yes&episode_watched_at=yes&episode_tvdb_id=yes&episode_runtime=yes&include_all_episodes=yes&allow_rewatch=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:13:18Z' last_watched_at: '2026-05-15T00:13:18Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 73 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' memo: {} is_rewatch: false seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-15T00:13:18Z' ids: tvdb_id: 3254641 runtime: 61 - number: 2 watched_at: '2026-05-15T00:13:18Z' ids: tvdb_id: 3436411 runtime: 55 - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T14:02:10Z' user_rated_at: null user_rating: null status: completed last_watched: S01E02 next_to_watch: null watched_episodes_count: 2 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' memo: {} is_rewatch: true rewatch_id: 7482 rewatch_status: active seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' ids: tvdb_id: 3254641 runtime: 61 - number: 2 watched_at: '2026-05-16T14:02:10Z' ids: tvdb_id: 3436411 runtime: 55 anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' memo: {} anime_type: tv mapped_tvdb_seasons: - 1 is_rewatch: false seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-15T00:13:09Z' tvdb: season: 1 episode: 1 ids: tvdb_id: 219121 runtime: 30 - number: 2 watched_at: '2026-05-15T00:13:09Z' tvdb: season: 1 episode: 2 ids: tvdb_id: 219122 runtime: 30 - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T14:02:10Z' user_rated_at: null user_rating: null status: completed last_watched: E2 next_to_watch: null watched_episodes_count: 2 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' memo: {} anime_type: tv mapped_tvdb_seasons: - 1 is_rewatch: true rewatch_id: 7484 rewatch_status: active seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' tvdb: season: 1 episode: 1 ids: tvdb_id: 219121 runtime: 30 - number: 2 watched_at: '2026-05-16T14:02:10Z' tvdb: season: 1 episode: 2 ids: tvdb_id: 219122 runtime: 30 movies: - added_to_watchlist_at: '2026-04-10T20:13:02Z' last_watched_at: '1994-09-01T16:00:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' memo: {} is_rewatch: false - added_to_watchlist_at: '2026-04-11T11:44:27Z' last_watched_at: '2026-04-11T11:30:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' memo: {} is_rewatch: true rewatch_id: 2368 rewatch_status: completed '400': description: >- `max_items` — the response would be too large to build. In practice a very large library requested with `extended=full`, especially with `include_all_episodes=yes`. Retrying unchanged returns the same error: split the request into one status per call, or use `include_all_episodes=original`. See [If a pull returns 400 max_items](/guides/sync#max-items). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: max_items code: 400 message: >- Too many episodes: … Use date_from, request one type/status per call, or drop extended/include_all_episodes '401': $ref: '#/components/responses/Unauthorized' '412': $ref: '#/components/responses/ClientIdFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' security: - clientId: [] bearerAuth: [] - simklApiKey: [] bearerAuth: [] x-codeSamples: - lang: curl label: phase1_initial_full_pull source: >- curl 'https://api.simkl.com/sync/all-items?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: phase2_incremental_delta source: >- curl 'https://api.simkl.com/sync/all-items?extended=full&episode_watched_at=yes&date_from=2026-05-14T00:00:00Z&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: movies_completed_filtered source: >- curl 'https://api.simkl.com/sync/all-items/movies/completed?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: watching_with_next_to_watch_info source: >- curl 'https://api.simkl.com/sync/all-items/shows/watching?next_watch_info=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: extended_full_with_seasons source: >- curl 'https://api.simkl.com/sync/all-items/shows/watching?extended=full&episode_watched_at=yes&episode_runtime=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: anime_with_mapped_tvdb_seasons source: >- curl 'https://api.simkl.com/sync/all-items/anime/completed?extended=full_anime_seasons&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: simkl_ids_only_minimal source: >- curl 'https://api.simkl.com/sync/all-items?extended=simkl_ids_only&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: ids_only_with_externals source: >- curl 'https://api.simkl.com/sync/all-items/movies/completed?extended=ids_only&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: rewatches_via_allow_rewatch source: >- curl 'https://api.simkl.com/sync/all-items/all/completed?extended=full&episode_watched_at=yes&allow_rewatch=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: all_modifiers_inspection_only source: >- curl 'https://api.simkl.com/sync/all-items?extended=full_anime_seasons&memos=yes&next_watch_info=yes&episode_watched_at=yes&episode_tvdb_id=yes&episode_runtime=yes&include_all_episodes=yes&allow_rewatch=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' components: schemas: WatchlistStatus: type: string enum: - watching - plantowatch - hold - completed - dropped description: >- User watchlist status. Movies skip `watching` and `hold` — see /conventions/list-statuses. AllItemsResponse: type: object description: >- Top-level dict keyed by `shows`, `movies`, and `anime`. Each key is an array of `AllItemsEntry` objects. **Keys are present only when there's at least one item in that bucket** — an empty library returns `{}`; a library with only movies returns `{ movies: [...] }` with no `shows` or `anime` keys. properties: shows: type: array items: $ref: '#/components/schemas/AllItemsEntry' movies: type: array items: $ref: '#/components/schemas/AllItemsEntry' anime: type: array items: $ref: '#/components/schemas/AllItemsEntry' 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 AllItemsEntry: type: object description: >- One item in the user's library. The exact set of fields present depends on the `extended` query parameter: - **no `extended`** (default): metadata fields + `` block with `ids` + watch state - **`extended=simkl_ids_only`**: ONLY `.ids: {simkl, slug}` — smallest payload, ideal for `date_from` deltas - **`extended=ids_only`**: ONLY `.ids` including all external IDs (imdb, tmdb, tvdb, mal, anidb, anilist, kitsu) - **`extended=full`**: adds `.runtime` and (for shows/anime with episodes loaded) `seasons[].episodes[]` - **`extended=full_anime_seasons`**: same as `full` plus `mapped_tvdb_seasons` on anime entries properties: added_to_watchlist_at: type: - string - 'null' format: date-time description: >- ISO-8601 timestamp when the user added this item to their watchlist. **Type 4 null** — `null` for legacy entries without a recorded add-time. See [Null and missing values](/conventions/null-values). example: '2026-05-15T00:35:15Z' last_watched_at: type: - string - 'null' format: date-time description: >- ISO-8601 timestamp of the most recent watch event. **Type 4 null** — `null` if the user has never watched any episode (e.g. `plantowatch` items). See [Null and missing values](/conventions/null-values). example: '2026-05-15T00:35:15Z' user_rated_at: type: - string - 'null' format: date-time description: >- ISO-8601 timestamp when the user set their rating. **Type 4 null** — `null` if not rated. See [Null and missing values](/conventions/null-values). user_rating: type: - integer - 'null' minimum: 1 maximum: 10 description: >- The user's rating (1-10). **Type 4 null** — `null` if not rated. See [Null and missing values](/conventions/null-values). status: type: string enum: - watching - plantowatch - hold - completed - dropped - notinteresting description: >- Current watchlist status. Apps with `client_id` ≤ 45340 see `notinteresting` everywhere `dropped` would appear (legacy compat). Newer apps see `dropped`. Movies skip `watching` and `hold` per [Watchlist statuses](/conventions/list-statuses). last_watched: type: - string - 'null' description: >- Most recently watched episode marker (e.g. `"S05E16"`). **Type 4 null** — `null` on movies (no episodes) and on shows/anime where no episode has been watched yet. example: S05E16 next_to_watch: type: - string - 'null' description: >- Next episode marker (e.g. `"S08E03"`) — the first unwatched regular episode after the last one the user watched. Specials never count. **Returned for every status**, not just `watching`: a `dropped` or `hold` entry normally still carries one. It is the answer to "is there anything left to watch?", which is not the same question as "what status is this in?". **Type 4 null** — `null` when no aired episode remains after the last watched one, which includes a user who watched the newest episode but skipped older ones, and `null` when nothing has aired yet. An item the user added but never started reports `S01E01` once an episode airs. Use `null` as the test for "caught up" rather than comparing the episode counts — see [Hide shows the user is caught up on](/guides/sync#hide-caught-up-shows). Omitted entirely on movies, and on `extended=ids_only` / `extended=simkl_ids_only` responses. example: S08E03 watched_episodes_count: type: integer description: >- Regular episodes the user has marked watched. Specials are not counted. Not tied to status: a `plantowatch` item can carry real progress if the user moved a part-watched show back. On `completed` items it always equals `total_episodes_count`. `0` on movies. total_episodes_count: type: integer description: >- Total regular episodes in the series, including ones that have not aired. Subtract `not_aired_episodes_count` for the aired count. `0` on movies. **This can go stale in a delta-only cache.** It is refreshed as episodes air or are added, and that refresh does not bump `/sync/activities` or put the item into a `date_from` delta — see [Episode counts can go stale](/guides/sync#episode-counts-can-go-stale). not_aired_episodes_count: type: integer description: >- Episodes not yet aired. An episode with no air date counts as not aired. `0` on movies, and `0` on `completed` series. Same staleness caveat as `total_episodes_count`: prefer `next_to_watch` over arithmetic on these two for "anything left to watch?". show: type: object description: >- Present for `shows` and `anime` entries (mutually exclusive with `movie`). properties: title: type: string example: The Walking Dead poster: type: - string - 'null' description: >- Type 4 null — no poster on file for this title. See [Null and missing values](/conventions/null-values). example: 16/16913426086fc13 year: type: - integer - 'null' description: >- Type 4 null — release year not on file. See [Null and missing values](/conventions/null-values). example: 2010 runtime: type: - integer - 'null' description: >- Type 4 null — episode runtime not on file. Present only with `extended=full` or `extended=full_anime_seasons`. See [Null and missing values](/conventions/null-values). example: 43 ids: type: object additionalProperties: true description: >- Always includes `simkl` + `slug`. With `extended=ids_only` or higher, includes all external IDs Simkl has on file (imdb, tmdb, tvdb, mal, anidb, anilist, kitsu, etc.). movie: type: object description: Present for `movies` entries (mutually exclusive with `show`). properties: title: type: string example: The Godfather poster: type: - string - 'null' description: >- Type 4 null — no poster on file for this title. See [Null and missing values](/conventions/null-values). year: type: - integer - 'null' description: >- Type 4 null — release year not on file. See [Null and missing values](/conventions/null-values). runtime: type: - integer - 'null' description: >- Type 4 null — runtime not on file. Present only with `extended=full`. See [Null and missing values](/conventions/null-values). ids: type: object additionalProperties: true description: >- Always includes `simkl` + `slug`. With `extended=ids_only` or higher, includes all external IDs. anime_type: type: - string - 'null' enum: - tv - movie - ova - ona - special - music video - null description: >- Type 4 null — anime_type unknown for this title. Present only on `anime[]` entries. The MyAnimeList-style classification of the anime title. See [Null and missing values](/conventions/null-values). mapped_tvdb_seasons: type: array items: type: integer description: >- Present only on `anime[]` entries with `extended=full_anime_seasons`. TVDB season numbers this anime maps to. memo: oneOf: - type: object properties: text: type: string is_private: type: boolean - type: object description: Empty object `{}` when no memo is set. description: >- Present only with `memos=yes`. The user's per-item memo, or an empty object `{}` when no memo is set. See [`POST /sync/history`](/api-reference/simkl/add-to-history) for setting memos. next_to_watch_info: type: object description: >- Present only with `next_watch_info=yes` AND `status: watching` AND there is a next episode to watch. properties: title: type: string example: How the West Was 1010001 season: type: integer description: Omitted for anime entries. episode: type: integer date: type: - string - 'null' format: date-time description: >- Type 4 null — release date not on file for the next episode. Format is ISO-8601 with timezone offset. See [Null and missing values](/conventions/null-values). seasons: type: array description: >- Per-season breakdown. Present only with `extended=full` (or `extended=full_anime_seasons`) AND the item is `watching` (or `include_all_episodes=yes` for `completed`/`dropped`). items: type: object properties: number: type: integer episodes: type: array items: type: object properties: number: type: integer watched_at: type: string format: date-time description: >- Per-episode watch timestamp. Present only with `episode_watched_at=yes`. tvdb: type: object description: >- Present only with `extended=full_anime_seasons` on anime entries. properties: season: type: integer episode: type: integer ids: type: object description: Present only with `episode_tvdb_id=yes`. properties: tvdb_id: type: integer runtime: type: - integer - 'null' description: >- Episode runtime in whole minutes. Present only with `episode_runtime=yes`. **Type 4 null** — `null` when no runtime is on file for that episode. See [Null and missing values](/conventions/null-values). example: 30 is_rewatch: type: boolean description: >- Present only with `allow_rewatch=yes`. `true` on synthesized rewatch-session entries; `false` on the canonical entry. See the [Rewatches guide](/guides/rewatches). Simkl PRO / VIP feature. rewatch_id: type: integer description: 'Present only on rewatch entries (`is_rewatch: true`).' rewatch_status: type: string enum: - active - completed - closed description: Present only on rewatch entries. additionalProperties: true parameters: AllItemsLanguageQuery: name: language in: query required: false schema: type: string enum: - en example: en description: >- `en` forces English titles. It's the only accepted value — any other value is ignored and titles fall back to the user's profile language. AllItemsAnimeTypeQuery: name: anime_type in: query required: false schema: type: string enum: - movies description: >- When `movies`, restricts the `anime` results to anime-movie subtype only. ClientIdQuery: name: client_id in: query required: true description: >- Your **`client_id`** from your [Simkl developer settings](https://simkl.com/settings/developer/). Required on every request. schema: type: string example: YOUR_CLIENT_ID AppNameQuery: name: app-name in: query required: true description: >- Short, lowercase identifier for your app (e.g. `plex-scrobbler`, `kodi-bridge`). Helps Simkl identify which apps are using the API. schema: type: string example: my-app AppVersionQuery: name: app-version in: query required: true description: >- Your app's current version (e.g. `1.0`, `2.4.1`). Helps Simkl debug issues you report. schema: type: string example: '1.0' UserAgentHeader: name: User-Agent in: header required: true description: >- Descriptive identifier for your app, ideally `name/version`. Examples: `PlexMediaServer/1.43.1.10540`, `kodi-simkl/0.9.2`, `MyApp/2.4.1 (https://myapp.com)`. schema: type: string example: my-app/1.0 responses: Unauthorized: description: >- Missing or invalid user access token. Provide a valid `Authorization: Bearer ` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: user_token_failed code: 401 ClientIdFailed: description: >- Your `client_id` is missing, wrong, disabled, or has hit a request limit. Verify in your [developer settings](https://simkl.com/settings/developer/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: client_id_failed code: 412 message: Your client_id is wrong. Try another one RateLimited: description: >- Too many requests in too short a window. Back off and retry with exponential backoff — see [Rate limits](/resources/rate-limits) for the playbook. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit code: 429 ServerError: description: >- Something is broken on Simkl's side. Retry after a short delay. If it persists, report on the [Simkl Discord](https://discord.gg/MJsWNE4). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: internal code: 500 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.