Pause
Saves the current progress as a resumable playback that any signed-in device can fetch via GET /sync/playback/{type} and resume with /scrobble/start. This is how Simkl powers cross-device “Continue Watching.” Does not mark the item watched. See the Playback overview for retention rules and the user-facing manager.
The body shape is identical to /scrobble/start.
Seek and scrub behavior
The progress you send is whatever the playhead is at the moment of pause — it doesn’t have to be larger than the prior start’s progress. A user who scrubs backward and pauses sends a smaller progress; that’s correct and the server stores it. Don’t call this endpoint on seek events themselves.
Note: A 20-second per-user lock collision returns HTTP
400withRATE_LIMIT, not429— the lock failure is treated as a malformed request from a duplicate-fire client.
Scrobble guide — full walkthrough
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).
Alternative to episode.season + episode.number: pass episode.ids with tvdb or anidb to identify the exact episode by external episode ID. Useful for Plex / media-server integrations that have a TVDB or AniDB episode ID but not the season/number mapping. (Episode-level imdb and tmdb IDs are not accepted — those exist only at the show/movie level. Use the show/anime object’s ids for those.) If both forms are sent, episode.ids takes precedence.
Rewatches
?allow_rewatch=yes has no effect here. Pausing marks nothing watched, so no rewatch session can be created and no rewatch_* keys are returned. Send it on POST /scrobble/stop or POST /scrobble/checkin instead. See the Rewatches guide.
Authorizations
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.
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.
Headers
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).
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Opt into rewatch tracking. When yes and the account is Simkl PRO or VIP, a /scrobble/stop with progress ≥ 80 on an already-completed item records a separate rewatch session instead of being a no-op, and the response gains rewatch_id + rewatch_status. Below 80 the stop is a pause, so nothing is marked and no rewatch fields are returned.
Send this on /scrobble/stop only. The flag is accepted here for consistency, but on /scrobble/start and /scrobble/checkin it applies to the user's previous outstanding playback rather than the item in this request, and nothing in the response reports that. See the /scrobble/stop description for the full rule.
Also supported on POST /scrobble/checkin, where the opt-in is stored on the check-in and applied later, when the check-in matures into a watch. The check-in response carries no rewatch fields because nothing has happened yet.
Read the Rewatches guide before enabling this. Gate it behind explicit user intent, a dedicated "Rewatch" button, never on automatic scrobble events, and expose a per-user Track rewatches toggle in your app settings that defaults to off. Used carelessly it pollutes the user's history stats and rewatches panel with phantom sessions.
yes, no Body
- Movie
- TV episode
- Anime episode
Request body for the four scrobble endpoints. Send exactly one of movie, show+episode, or anime+episode — all keys are singular objects (one item per request). For batch sync writes the keys are plural arrays: see /sync/history etc. progress is required for /scrobble/start, /scrobble/pause, and /scrobble/stop; on /scrobble/checkin it is optional and ignored server-side.
Anime under show? Yes — if you don't know whether a title is anime (e.g. you only have TMDB/TVDB data), send it under show and Simkl resolves it to the correct catalog automatically. The anime key is only needed when you want to pass anidb / mal / anilist IDs that don't exist at the TV-show level.
Movie reference. Use ids (any one external ID) and optionally title / year. Movies have no episode block.
Playback percentage 0-100. Up to 2 decimals. Required for /scrobble/start, /scrobble/pause, /scrobble/stop. Optional (and ignored) for /scrobble/checkin.
0 <= x <= 100TV show reference (must be paired with episode).
Anime reference. Pair with episode for series; an anime alone (no episode) is treated as an anime movie / OVA.
Episode identifier. Use season + number, OR ids with a tvdb / anidb episode ID. If both are sent, episode.ids takes precedence (matches Plex-style integrations that have an episode ID but no season/number mapping).
- By season + number
- By episode ID
Response
Created
Response for /scrobble/start, /scrobble/pause, /scrobble/stop and /scrobble/checkin.
rewatch_id and rewatch_status are present only on a scrobble action (a /scrobble/stop with progress >= 80) that was sent with ?allow_rewatch=yes. On every other call they are absent entirely.
Playback event id for this call. 0 on /scrobble/start (the handler only assigns an id once the session is no longer just opening). Pass it to the playback-removal endpoint to undo a stop.
start for /start, pause for /pause and for /stop with progress<80, scrobble for /stop with progress≥80 (item marked watched).
start, pause, scrobble Echo of the request progress, normalized.
Standard movie object. See the Standard Media Objects guide.
Standard show object. May include nested seasons/episodes for partial sync.
Standard anime object. Like Show, but may include anime_type. Episode numbering follows AniDB.
Episode object returned by the /scrobble/* endpoints. This is not the same shape as the Episode object accepted in sync request bodies: it carries a resolved title, and it has no ids map.
Type 4 null — the watch did not land on a rewatch session. See Null and missing values.
The rewatch session this watch was recorded on. Present only when ?allow_rewatch=yes was sent and action is scrobble — otherwise the key is absent entirely.
A session that is already running reports its id even when it rejected this watch (for example inside the 2-day gap), so this field alone does not tell you the watch was recorded. Read rewatch_status for that.
Type 4 null — the watch itself failed to record, so no rewatch was attempted. See Null and missing values.
What happened to this watch. Present only when ?allow_rewatch=yes was sent and action is scrobble — otherwise the key is absent entirely.
The first three values are session states, and mean the watch was recorded on a session of that state. The rest explain why no session took it. Note this is a superset of the three-value rewatch_status returned by GET /sync/all-items — do not reuse that enum here.
active — recorded on a session still in progress (typical for TV / anime).
completed — recorded on a session that is now complete; movie sessions are created complete.
closed — recorded on a session that was manually closed or left partial.
first_watch — not a re-viewing; this is the original watch.
too_soon — rejected by the 2-day gap between two watches of the same item.
not_eligible — the item's watchlist status is plan-to-watch.
pro_required — the account is not Simkl PRO or VIP.
active, completed, closed, first_watch, too_soon, not_eligible, pro_required, null