Check-in
A fire-and-forget version of /scrobble/start. Same effect on the user’s dashboard — the title appears in the “Watching now” widget with an animated, runtime-extrapolated progress bar — but you don’t need to follow up with pause / stop events. Simkl computes progress server-side from (now − checkin time) ÷ runtime; when that reaches 100%, the title is auto-marked watched.
Auto-completion timing: Once the computed progress reaches 100%, marking the item as watched can take anywhere from 0 to 2 minutes. Some check-ins finalize instantly; others sit at 100% briefly while the background worker picks them up. Don’t treat the delay as a failure — if you need to know exactly when it lands, check
GET /sync/activitiesafter the runtime expires; when the relevantcompleted/watchingtimestamp bumps, refresh viaGET /sync/all-items/{type}/{status}?date_from=…. That’s the same incremental loop documented in the Sync guide — no extra calls beyond what a normal sync would already do.
The user can browse and clean up active check-ins at the Playback progress manager.
When to use checkin vs the start / pause / stop loop
| Situation | Use |
|---|---|
| You have real player events (play / pause / stop) and want exact progress | /scrobble/start → /pause → /stop loop |
| You can’t reliably hook into pause / stop (some embedded players, casting flows, hardware AV-out, social “I’m watching this” buttons) | checkin |
| You just want to record a watch after the fact, no live status | POST /sync/history |
Seek and scrub behavior
No progress to update — the user can scrub or seek freely after check-in. The server’s runtime extrapolation doesn’t track real player position, so a user who checks in and then walks away is also auto-marked watched at the calculated runtime expiry. That’s a feature, not a bug, for fire-and-forget integrations.
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 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 is supported here. Send it when the user explicitly asked to log a rewatch and the account is Simkl PRO / VIP.
It works differently from /scrobble/stop, because a check-in marks nothing watched at request time. The opt-in is stored on the check-in and applied later, when the check-in matures into a watch at the end of the item’s runtime. Consequences:
- The response carries no
rewatch_id/rewatch_status. Nothing has happened yet. To see the result, read the sessions back fromGET /sync/all-items?allow_rewatch=yes. - The PRO / VIP check happens now, not later. A user who is PRO at check-in still gets the rewatch when it matures, even if the plan lapses in between.
- You cannot change your mind. The flag is fixed once the check-in is recorded. Deleting the playback before it matures cancels the whole check-in, rewatch included.
One side effect worth knowing: the flag also reaches the auto-scrobble of the user’s previous outstanding playback, which may be a different title. 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