Skip to main content

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.

A playback is a saved pause point. When a user pauses watching (/scrobble/pause) or stops before 80% progress (/scrobble/stop with progress < 80), Simkl persists the position so the user can resume from any signed-in device. Playbacks are how Simkl powers “Continue Watching” UIs. This page is a reference index. The lifecycle, cross-device flow, and full scrobble integration live in the Scrobble guide.
Playbacks are NOT the user’s watch history. A playback is a temporary “where I left off” record. It does not put the title on the user’s watched list, does not count toward completion stats, and disappears once the user finishes the item, deletes it, or the retention window expires.To actually mark an item as watched, use one of:
  • POST /sync/history — adds the item to the watched library directly. No scrobble session required.
  • POST /scrobble/stop with progress ≥ 80 — finishes a live scrobble session and writes a watch-history entry in the same call.
  • POST /scrobble/checkin — fire-and-forget; Simkl auto-marks the item watched once the runtime elapses.
If you only need a “Mark as watched” button (no playback tracking), POST /sync/history is the simplest path — see the Mark as watched guide.
Members can browse and clean up their saved playbacks at simkl.com/my/history/playback-progress-manager/.

​
What gets stored

TriggerResult
POST /scrobble/pause (any progress)Saves a paused playback at the sent progress.
POST /scrobble/stop with progress < 80Saves a paused playback at the sent progress (resumable).
POST /scrobble/stop with progress ≥ 80No playback saved — item is written to watch history instead (same as POST /sync/history).
POST /scrobble/checkinNo playback saved (the runtime-extrapolated session lives elsewhere).
Only one paused playback per show / movie / anime is kept. A new pause replaces the previous one for that title.

​
Retention by plan

Saved playbacks are pruned automatically by a daily cleanup job:
PlanRetention
Free7 days
PRO30 days
VIP90 days
After the retention window, the playback is deleted unconditionally and can no longer be resumed.

​
Cross-device resume — the recipe

Device A pauses, Device B picks it up:
1

Device A pauses

POST /scrobble/pause with the user’s access_token and current progress. Simkl saves the position.
2

Device B gates the refetch on activities

POST /sync/activities returns a playback timestamp per media-type bucket. Compare it to the value you saved on the previous sync — if it hasn’t moved, no new pause has happened and you can skip the next step.
{
  "all":      "2026-04-19T12:14:08Z",
  "movies":   { "playback": "2026-04-19T12:14:08Z", ... },
  "tv_shows": { "playback": "2026-04-15T08:31:55Z", ... },
  "anime":    { "playback": "2026-04-12T19:02:11Z", ... }
}
3

Device B asks for any saved playbacks

Only when the playback timestamp moved: GET /sync/playback (or narrow with /sync/playback/episodes / /sync/playback/movies) returns the paused playbacks for this user. Save the new timestamp.
4

Device B resumes

POST /scrobble/start with the same item and the saved progress. The session continues; the prior pause is automatically cleared.
Don’t poll /sync/playback on a timer. Always gate refetches on the playback timestamp from /sync/activities — that endpoint is the cheap “is anything new?” check. Idle accounts won’t trip the gate, so quota stays free for active users. The same pattern applies to every Sync surface (history, watchlist, ratings); see the Sync guide for the full strategy.
Both devices use the same access_token — the playback is stored per-user, not per-device.
Simkl user dashboard showing 'NOW WATCHING' Fallout S02E07 'The Handoff' resumed at 46%, 27 minutes left

​
Endpoints

Get playbacks

GET /sync/playback — list saved paused playbacks for a user (or narrow with /sync/playback/:type where :type is episodes or movies). Filter by date_from, date_to, hide_watched, limit.

Delete playback

DELETE /sync/playback/:id — remove a saved playback by its ID.

​
Item shape

Each playback in the response includes:
  • id — 64-bit integer playback ID (use this with the DELETE endpoint)
  • progress — percentage 0-100 (e.g. 42, 75.5)
  • paused_at — ISO-8601 UTC timestamp
  • type — "episode" or "movie"
  • For episodes: episode.{season, number, title} plus tvdb_season / tvdb_number for anime
  • The container object: show (TV episodes), anime (anime episodes), or movie. Each carries title, year, and ids.

Add to history

POST /sync/history — the canonical “mark as watched” endpoint. Use this (not playback) when you want a title on the user’s watched library.

Mark as watched guide

Pick the right write endpoint when you don’t need real-time playback tracking.

Scrobble guide

The full scrobble lifecycle, including how pause/stop create playbacks.

How scrobbling works

API reference index for the four scrobble endpoints.

Activities

POST /sync/activities — the “is anything new?” gate. Check the playback timestamp before refetching.

Sync guide

The activities-driven refresh strategy applied across all user data.