> ## 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 one type

> Returns the user's saved paused playbacks — created by `/scrobble/pause` or `/scrobble/stop` with progress < 80%. The `{type}` segment is optional:

| Path | Returns |
|---|---|
| `GET /sync/playback` | All paused playbacks (episodes + movies). |
| `GET /sync/playback/episodes` | TV/anime episode playbacks only. |
| `GET /sync/playback/movies` | Movie playbacks only. |

The response shape is identical across the three forms; only the included items differ. Resume a session by calling [`/scrobble/start`](/api-reference/simkl/scrobble-start) with the same item.

#### Query parameters

| Param | Effect | Default |
|---|---|---|
| `date_from` | Only sessions with `paused_at >= date_from`. | — |
| `date_to` | Only sessions with `paused_at < date_to`. | — |
| `hide_watched` | Exclude items already watched after the pause was created. | `true` |
| `limit` | Max items returned (1–10000). | `10000` |

#### Item shape

```json
{
  "id": 12345,
  "progress": 42.2,
  "paused_at": "2024-04-30T22:13:00Z",
  "type": "episode",
  "episode": {
    "season": 1,
    "number": 3,
    "title": "Chapter Three: Holly Jolly",
    "tvdb_season": 1,
    "tvdb_number": 3
  },
  "show": {
    "title": "Stranger Things",
    "year": 2016,
    "ids": {
      "simkl": 39687,
      "imdb": "tt4574334",
      "tvdb": 305288
    }
  }
}
```

> Note: `progress` is a **percentage (0-100)** — same scale as the scrobble endpoints. The example values shown above (`75`, `45.5`, `42.2`) are real outputs from the API.

Members can browse and clean these up at [simkl.com/my/history/playback-progress-manager](https://simkl.com/my/history/playback-progress-manager/).

#### Retention by plan

- **Free** — 7 days · **PRO** — 30 days · **VIP** — 90 days

Sessions persist until they're manually removed via [`DELETE /sync/playback/{id}`](/api-reference/simkl/delete-playback), replaced by the next scrobble update on the same title, or aged out per the plan retention window above. They are not auto-deleted on `paused_at` expiry — you'll see the same session in the response indefinitely until one of those three things happens.

<Card title="Scrobble guide — full walkthrough" icon="play" href="/guides/scrobble" horizontal>
 Real-time playback tracking — `/start`, `/pause`, `/stop` lifecycle, paused-playback resumption across devices, when scrobble auto-completes, and the difference between `/scrobble/checkin` (fire-and-forget) and `/scrobble/start` (active tracking).
</Card>

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



## OpenAPI

````yaml /openapi.json get /sync/playback/{type}
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 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.
externalDocs:
  description: Simkl API documentation
  url: https://api.simkl.org
paths:
  /sync/playback/{type}:
    get:
      tags:
        - Sync
      summary: Get paused playback sessions for one type
      description: >-
        Returns the user's saved paused playbacks — created by `/scrobble/pause`
        or `/scrobble/stop` with progress < 80%. The `{type}` segment is
        optional:


        | Path | Returns |

        |---|---|

        | `GET /sync/playback` | All paused playbacks (episodes + movies). |

        | `GET /sync/playback/episodes` | TV/anime episode playbacks only. |

        | `GET /sync/playback/movies` | Movie playbacks only. |


        The response shape is identical across the three forms; only the
        included items differ. Resume a session by calling
        [`/scrobble/start`](/api-reference/simkl/scrobble-start) with the same
        item.


        #### Query parameters


        | Param | Effect | Default |

        |---|---|---|

        | `date_from` | Only sessions with `paused_at >= date_from`. | — |

        | `date_to` | Only sessions with `paused_at < date_to`. | — |

        | `hide_watched` | Exclude items already watched after the pause was
        created. | `true` |

        | `limit` | Max items returned (1–10000). | `10000` |


        #### Item shape


        ```json

        {
          "id": 12345,
          "progress": 42.2,
          "paused_at": "2024-04-30T22:13:00Z",
          "type": "episode",
          "episode": {
            "season": 1,
            "number": 3,
            "title": "Chapter Three: Holly Jolly",
            "tvdb_season": 1,
            "tvdb_number": 3
          },
          "show": {
            "title": "Stranger Things",
            "year": 2016,
            "ids": {
              "simkl": 39687,
              "imdb": "tt4574334",
              "tvdb": 305288
            }
          }
        }

        ```


        > Note: `progress` is a **percentage (0-100)** — same scale as the
        scrobble endpoints. The example values shown above (`75`, `45.5`,
        `42.2`) are real outputs from the API.


        Members can browse and clean these up at
        [simkl.com/my/history/playback-progress-manager](https://simkl.com/my/history/playback-progress-manager/).


        #### Retention by plan


        - **Free** — 7 days · **PRO** — 30 days · **VIP** — 90 days


        Sessions persist until they're manually removed via [`DELETE
        /sync/playback/{id}`](/api-reference/simkl/delete-playback), replaced by
        the next scrobble update on the same title, or aged out per the plan
        retention window above. They are not auto-deleted on `paused_at` expiry
        — you'll see the same session in the response indefinitely until one of
        those three things happens.


        <Card title="Scrobble guide — full walkthrough" icon="play"
        href="/guides/scrobble" horizontal>
         Real-time playback tracking — `/start`, `/pause`, `/stop` lifecycle, paused-playback resumption across devices, when scrobble auto-completes, and the difference between `/scrobble/checkin` (fire-and-forget) and `/scrobble/start` (active tracking).
        </Card>


        <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>
      operationId: get-sync-playback-type
      parameters:
        - $ref: '#/components/parameters/PlaybackTypeQuery'
        - $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:
    PlaybackTypeQuery:
      name: type
      in: path
      description: >-
        `episodes` or `movies` to filter by item type. To get all paused
        playbacks of both kinds, call `GET /sync/playback`. Strictness; drop the
        segment from the URL to call without it.
      schema:
        type: string
        enum:
          - movies
          - episodes
      example: movies
      required: true
    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: When `true`, hides items already watched after the pause was created.
    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:
          oneOf:
            - type: integer
            - type: string
          description: TVDB ID or slug.
          example: 153021
        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: >-
        OAuth 2.0 or PIN-flow `access_token`. Required for endpoints that read
        or modify the user's library, scrobble session, ratings, settings, or
        playbacks. See [Authentication](/authentication).
      x-default: YOUR_ACCESS_TOKEN

````