Start
Creates or replaces the user’s active “watching now” session for the given item. Call this when playback begins, or to resume a previously paused session.
Body shape
Send progress plus exactly one of movie, show+episode, or anime+episode. See Standard media objects.
| Field | Type | Notes |
|---|---|---|
progress | float | 0–100, max 2 decimals. Response normalizes to 75 not 75.00. |
movie / show / anime | object | Title + year + ids. simkl ID alone is enough. |
episode | object | season + number, or ids. Required for shows/anime. |
Behavior
- Replaces any existing session for this item and clears prior pauses.
- Auto-expires after the calculated remaining runtime.
- If a previous start/checkin reached ≥ 80 % before this call, it is auto-scrobbled (marked watched) before the new session starts.
- Response shape:
id,action,progress, plus the media object withids(incl. external links Simkl knows about) and anepisodeblock. For anime, the response includes both AniDB-canonicalseason/numberand originaltvdb_season/tvdb_number.
Seek and scrub behavior
Don’t call /scrobble/start on a seek event. Only call it when playback actually begins or resumes (typically the player’s play event). When a user scrubs to a different position before pressing play, just update your local progress; the eventual play event fires the call with the new value.
Errors
| Code | When |
|---|---|
400empty_field | No movie, show, or anime in the body. |
400RATE_LIMIT | A 20-second per-user lock collision — another scrobble write for this user landed within the window. Note: HTTP 400, not 429 — the lock failure is treated as a malformed request from a duplicate-fire client. |
401user_token_failed | Missing / invalid bearer token. |
404id_err | Item could not be matched. |
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 is accepted here but should not be sent. This endpoint marks nothing watched, so it never returns rewatch_id / rewatch_status. Worse, it auto-scrobbles the user’s previous outstanding playback once that reaches 80%, and the flag is honoured on that path — which may be a different title, with nothing in the response to report it. 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