> ## 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 paused playback sessions for every type

> Returns the user's paused playback sessions across all types (movies, shows, anime). For a single type see [`GET /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions).

Useful for "Continue Watching" rails that mix types.

<Tip>
**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).
</Tip>

#### Already-watched items can appear here

A paused playback is returned **even when the user has already finished that title**, as long as the pause happened *after* they finished it. That is a re-viewing in progress, not stale data, and `hide_watched=true` (the default) deliberately does not filter it out.

So a Continue Watching row built from this endpoint can contain a movie or episode the user has completed before. If your UI also shows a "watched" checkmark, expect both to be true at once — show the resume position anyway.

`hide_watched=true` only removes playbacks that were **overtaken**: paused first, then marked watched from somewhere else. Those are genuine leftovers.

This changed in August 2026. Previously a completed movie, or the exact episode the watchlist last pointed at, was hidden regardless of when it was watched, which meant re-viewings never showed up.




## OpenAPI

````yaml /openapi.json get /sync/playback
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 <token>` 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.


      <!-- IDS_TABLE_START -->


      ### 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)


      <!-- IDS_TABLE_END -->
    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.


      <!-- IDS_TABLE_START -->


      ### 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)


      <!-- IDS_TABLE_END -->
    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/playback:
    get:
      tags:
        - Sync
      summary: Get paused playback sessions for every type
      description: >
        Returns the user's paused playback sessions across all types (movies,
        shows, anime). For a single type see [`GET
        /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions).


        Useful for "Continue Watching" rails that mix types.


        <Tip>

        **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).

        </Tip>


        #### Already-watched items can appear here


        A paused playback is returned **even when the user has already finished
        that title**, as long as the pause happened *after* they finished it.
        That is a re-viewing in progress, not stale data, and
        `hide_watched=true` (the default) deliberately does not filter it out.


        So a Continue Watching row built from this endpoint can contain a movie
        or episode the user has completed before. If your UI also shows a
        "watched" checkmark, expect both to be true at once — show the resume
        position anyway.


        `hide_watched=true` only removes playbacks that were **overtaken**:
        paused first, then marked watched from somewhere else. Those are genuine
        leftovers.


        This changed in August 2026. Previously a completed movie, or the exact
        episode the watchlist last pointed at, was hidden regardless of when it
        was watched, which meant re-viewings never showed up.
      operationId: get-sync-playback-all
      parameters:
        - $ref: '#/components/parameters/PlaybackLimitQuery'
        - $ref: '#/components/parameters/PlaybackHideWatchedQuery'
        - $ref: '#/components/parameters/PlaybackDateFromQuery'
        - $ref: '#/components/parameters/PlaybackDateToQuery'
        - $ref: '#/components/parameters/ClientIdQuery'
        - $ref: '#/components/parameters/AppNameQuery'
        - $ref: '#/components/parameters/AppVersionQuery'
        - $ref: '#/components/parameters/UserAgentHeader'
      responses:
        '200':
          $ref: '#/components/responses/PlaybackListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/ClientIdFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - clientId: []
          bearerAuth: []
        - simklApiKey: []
          bearerAuth: []
components:
  parameters:
    PlaybackLimitQuery:
      name: limit
      in: query
      description: 'Slice your result to the first N items. Default: 10000'
      schema:
        type: number
    PlaybackHideWatchedQuery:
      name: hide_watched
      in: query
      schema:
        type: string
        enum:
          - 'true'
          - 'false'
        default: 'true'
      description: >-
        Controls whether playbacks for items the user has **already finished**
        are filtered out.


        `true` (default) hides a paused playback only when the item was watched
        **at or after** the moment it was paused — a stale leftover, e.g. the
        user paused at 40% and then marked the whole thing watched from another
        app.


        It does **not** hide a playback that was paused *after* the item was
        finished. That is a **re-viewing in progress**, and it is returned even
        with `hide_watched=true`. A user who finished a film years ago and is
        45% into watching it again gets that playback back in the list, which is
        what a Continue Watching row should show.


        `false` skips the check entirely, including the stale-leftover case.


        One edge case: for items whose watch date is the "watched, date unknown"
        placeholder there is no date to compare, so `true` falls back to hiding
        completed movies and the specific episode the watchlist last pointed at.
    PlaybackDateFromQuery:
      name: date_from
      in: query
      description: Filter sessions from this date
      schema:
        type: string
    PlaybackDateToQuery:
      name: date_to
      in: query
      description: Filter sessions until this date
      schema:
        type: string
    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:
    PlaybackListResponse:
      description: OK
      headers: {}
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PlaybackSession'
          example:
            - id: 123
              progress: 45.5
              paused_at: '2024-01-15T10:30:00.000Z'
              type: episode
              episode:
                season: 1
                episode: 5
                title: Episode 5
                tvdb_season: 1
                tvdb_number: 5
              show:
                title: Breaking Bad
                year: 2008
                ids:
                  simkl: 12345
                  slug: breaking-bad
                  tmdb: '1429'
                  imdb: tt0903747
            - id: 124
              progress: 75
              paused_at: '2024-01-15T11:15:00.000Z'
              type: movie
              movie:
                title: Inception
                year: 2010
                ids:
                  simkl: 67890
                  slug: inception
                  tmdb: '27205'
                  imdb: tt1375666
    Unauthorized:
      description: >-
        Missing or invalid user access token. Provide a valid `Authorization:
        Bearer <access_token>` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: user_token_failed
            code: 401
    NotFound:
      description: The requested item ID or URL does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: id_err
            code: 404
    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
  schemas:
    PlaybackSession:
      type: object
      description: A saved (paused) playback session.
      properties:
        id:
          type: integer
          description: >-
            Internal playback session ID. Use to delete via DELETE
            /sync/playback/{id}.
        progress:
          type: number
          description: Saved progress percentage 0–100.
        watched_at:
          type: string
          format: date-time
        movie:
          $ref: '#/components/schemas/Movie'
        show:
          $ref: '#/components/schemas/Show'
        anime:
          $ref: '#/components/schemas/Anime'
        episode:
          $ref: '#/components/schemas/Episode'
    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
    Movie:
      type: object
      description: >-
        Standard movie object. See the [Standard Media
        Objects](/conventions/standard-media-objects) guide.
      properties:
        title:
          type: string
          example: 'Terminator 3: Rise of the Machines'
        year:
          type: integer
          example: 2003
        ids:
          $ref: '#/components/schemas/Ids'
      required:
        - ids
    Show:
      type: object
      description: >-
        Standard show object. May include nested seasons/episodes for partial
        sync.
      properties:
        title:
          type: string
          example: The Walking Dead
        year:
          type: integer
          example: 2010
        ids:
          $ref: '#/components/schemas/Ids'
        seasons:
          type: array
          items:
            type: object
            properties:
              number:
                type: integer
              episodes:
                type: array
                items:
                  $ref: '#/components/schemas/Episode'
      required:
        - ids
    Anime:
      type: object
      description: >-
        Standard anime object. Like Show, but may include `anime_type`. Episode
        numbering follows AniDB.
      properties:
        title:
          type: string
          example: Attack on Titan
        year:
          type: integer
          example: 2013
        anime_type:
          $ref: '#/components/schemas/AnimeFormat'
        ids:
          $ref: '#/components/schemas/Ids'
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/Episode'
      required:
        - ids
    Episode:
      type: object
      description: Episode reference. Use `season` + `number`, or `ids`.
      properties:
        season:
          type: integer
          minimum: 0
          example: 1
        number:
          type: integer
          minimum: 1
          example: 2
        watched_at:
          type: string
          format: date-time
          example: '2014-09-01T09:10:11Z'
          description: ISO-8601 GMT timestamp.
        ids:
          $ref: '#/components/schemas/Ids'
    Ids:
      type: object
      description: >-
        External and internal identifiers for an item. Pass as many as you have
        — Simkl resolves to the canonical record.
      properties:
        simkl:
          type: integer
          description: Simkl internal ID. Most reliable.
          example: 53536
        slug:
          type: string
          description: URL-safe slug returned in responses.
          example: attack-on-titan
        imdb:
          type: string
          description: IMDb ID.
          example: tt0181852
        tmdb:
          type: string
          description: TMDb ID.
          example: '296'
        tvdb:
          description: TVDB ID or slug.
          example: '153021'
          type: string
        mal:
          type: string
          description: MyAnimeList ID.
          example: '4246'
        anidb:
          type: string
          description: AniDB ID. Specifying just this is enough for anime lookups.
          example: '10846'
        anilist:
          type: string
          description: AniList ID.
          example: '21'
        kitsu:
          type: string
          description: Kitsu ID.
          example: '12'
        anisearch:
          type: string
          description: aniSearch ID.
          example: '2227'
        animeplanet:
          type: string
          description: Anime-Planet slug.
          example: one-piece
        livechart:
          type: string
          description: LiveChart ID.
          example: '321'
        letterboxd:
          type: string
          description: Letterboxd slug.
          example: the-truman-show
        netflix:
          type: string
          description: Netflix movie ID.
          example: '70210890'
        hulu:
          type: string
          description: Hulu episode ID.
        crunchyroll:
          type: string
          description: Crunchyroll episode ID.
        traktslug:
          type: string
          description: Trakt slug.
          example: john-wick-chapter-4-2023
      additionalProperties: true
      example:
        simkl: 53536
        imdb: tt0181852
        tmdb: '296'
    AnimeFormat:
      type: string
      enum:
        - tv
        - movie
        - special
        - ova
        - ona
        - music video
      description: >-
        Anime production format. `tv` is the common case; movies, OVAs, ONAs,
        and music videos all surface through the `/anime/*` endpoints with the
        same response shape.
  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

````