curl --request POST \
  --url 'https://api.simkl.com/scrobble/start?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

{
  "id": 0,
  "action": "start",
  "progress": 25,
  "episode": {
    "season": 1,
    "number": 1,
    "title": "Cruelty",
    "tvdb_season": 1,
    "tvdb_number": 1
  },
  "anime": {
    "title": "Kimetsu no Yaiba",
    "year": 2019,
    "anime_type": "tv",
    "ids": {
      "simkl": 831411,
      "slug": "kimetsu-no-yaiba",
      "imdb": "tt9335498",
      "mal": "38000",
      "tvdbslug": "demon-slayer-kimetsu-no-yaiba",
      "anilist": "101922",
      "kitsu": "41370",
      "trakttvslug": "demon-slayer-kimetsu-no-yaiba",
      "anidb": "14107",
      "tvdb": "348545",
      "tmdb": "85937"
    }
  }
}

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 with ids (incl. external links Simkl knows about) and an episode block. For anime, the response includes both AniDB-canonical season/number and original tvdb_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.

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

POST

scrobble

start

curl --request POST \
  --url 'https://api.simkl.com/scrobble/start?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

{
  "id": 0,
  "action": "start",
  "progress": 25,
  "episode": {
    "season": 1,
    "number": 1,
    "title": "Cruelty",
    "tvdb_season": 1,
    "tvdb_number": 1
  },
  "anime": {
    "title": "Kimetsu no Yaiba",
    "year": 2019,
    "anime_type": "tv",
    "ids": {
      "simkl": 831411,
      "slug": "kimetsu-no-yaiba",
      "imdb": "tt9335498",
      "mal": "38000",
      "tvdbslug": "demon-slayer-kimetsu-no-yaiba",
      "anilist": "101922",
      "kitsu": "41370",
      "trakttvslug": "demon-slayer-kimetsu-no-yaiba",
      "anidb": "14107",
      "tvdb": "348545",
      "tmdb": "85937"
    }
  }
}

Authorizations

client_id

string

query

default:YOUR_CLIENT_ID

required

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.

Authorization

string

header

default:YOUR_ACCESS_TOKEN

required

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.

Headers

User-Agent

string

required

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

client_id

string

required

Your client_id from your Simkl developer settings. Required on every request.

app-name

string

required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version

string

required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Body

application/json

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

object

required

Movie reference. Use ids (any one external ID) and optionally title / year. Movies have no episode block.

Hide child attributes

movie.ids

object

required

External IDs for a movie. Pass any one or more — Simkl resolves the canonical record by walking these in priority order. simkl is the most reliable when you have it.

Hide child attributes

movie.ids.simkl

integer

Simkl movie ID.

Example:

472214

movie.ids.slug

string

Simkl URL slug (echoed back in responses).

Example:

"inception"

movie.ids.imdb

string

IMDb ID, e.g. tt1375666.

Example:

"tt1375666"

movie.ids.tmdb

integer

TMDb movie ID.

Example:

27205

movie.ids.netflix

integer

Netflix movie ID.

movie.ids.traktslug

string

Trakt movie slug, e.g. inception-2010.

movie.ids.letterboxd

string

Letterboxd slug, e.g. inception.

movie.ids.boxd

string

Letterboxd numeric ID (alternative to letterboxd).

movie.title

string

Example:

"Inception"

movie.year

integer

Example:

2010

progress

number<float>

Playback percentage 0-100. Up to 2 decimals. Required for /scrobble/start, /scrobble/pause, /scrobble/stop. Optional (and ignored) for /scrobble/checkin.

Required range: 0 <= x <= 100

show

object

TV show reference (must be paired with episode).

Hide child attributes

show.ids

object

required

External IDs for a TV show. Pass any one or more.

Hide child attributes

show.ids.simkl

integer

Simkl show ID.

Example:

548312

show.ids.slug

string

Simkl URL slug (echoed back in responses).

Example:

"stranger-things"

show.ids.imdb

string

IMDb ID, e.g. tt4574334.

Example:

"tt4574334"

show.ids.tmdb

integer

TMDb show ID.

Example:

66732

show.ids.tvdb

TVDB show ID (integer) or slug (string).

Example:

305288

show.ids.netflix

integer

Netflix show ID.

show.ids.hulu

integer

Hulu show ID.

show.ids.traktslug

string

Trakt show slug.

show.ids.zap2it

string

Zap2it ID.

show.ids.tvcom

string

TV.com ID.

show.ids.mdl

string

MyDramaList slug or ID.

show.title

string

Example:

"Stranger Things"

show.year

integer

Example:

2016

anime

object

Anime reference. Pair with episode for series; an anime alone (no episode) is treated as an anime movie / OVA.

Hide child attributes

anime.ids

object

required

External IDs for an anime. Any one is enough; mal / anidb / anilist / kitsu are most useful for anime-only sources, while simkl, imdb, tmdb, and tvdb work for the cross-domain mapping.

Hide child attributes

anime.ids.simkl

integer

Simkl anime ID.

Example:

39687

anime.ids.slug

string

Simkl URL slug.

Example:

"shingeki-no-kyojin"

anime.ids.imdb

string

IMDb ID.

Example:

"tt2560140"

anime.ids.tmdb

integer

TMDb show or movie ID (depending on anime_type).

Example:

1429

anime.ids.tvdb

TVDB show ID (integer) or slug (string).

Example:

267440

anime.ids.mal

integer

MyAnimeList ID.

Example:

16498

anime.ids.anidb

integer

AniDB ID. Specifying just this is enough for anime lookups.

Example:

9541

anime.ids.anilist

integer

AniList ID.

Example:

16498

anime.ids.kitsu

integer

Kitsu ID.

Example:

7442

anime.ids.anisearch

integer

aniSearch ID.

anime.ids.animeplanet

string

Anime-Planet slug.

anime.ids.livechart

integer

LiveChart ID.

anime.ids.anfo

integer

AnimeNewsNetwork-style anfo ID.

anime.ids.ann

integer

AnimeNewsNetwork ID.

anime.title

string

Example:

"Shingeki no Kyojin"

anime.year

integer

Example:

2013

episode

By season + number · object

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

Hide child attributes

episode.season

integer

required

Season number. 0 is the specials season.

Required range: x >= 0

Example:

1

episode.number

integer

required

Episode number within the season.

Required range: x >= 1

Example:

3

episode.ids

object

External IDs for an episode. Only tvdb and anidb are accepted as scrobble episode-ID lookups. Pass either; if both are sent, tvdb is tried first.

Hide child attributes

episode.ids.tvdb

integer

TVDB episode ID.

Example:

4274616

episode.ids.anidb

integer

AniDB episode ID.

Example:

142278

Response

Created

Response for /scrobble/start, /scrobble/pause, and /scrobble/stop.

action

enum<string>

start for /start, pause for /pause and for /stop with progress<80, scrobble for /stop with progress≥80 (item marked watched).

Available options:

start,

pause,

scrobble

progress

number

Echo of the request progress, normalized.

sid

string

Internal session ID.

movie

object

Standard movie object. See the Standard Media Objects guide.

Hide child attributes

movie.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

movie.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

movie.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

movie.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

movie.ids.tmdb

string

TMDb ID.

Example:

"296"

movie.ids.tvdb

TVDB ID or slug.

Example:

153021

movie.ids.mal

string

MyAnimeList ID.

Example:

"4246"

movie.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

movie.ids.anilist

string

AniList ID.

Example:

"21"

movie.ids.kitsu

string

Kitsu ID.

Example:

"12"

movie.ids.anisearch

string

aniSearch ID.

Example:

"2227"

movie.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

movie.ids.livechart

string

LiveChart ID.

Example:

"321"

movie.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

movie.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

movie.ids.hulu

string

Hulu episode ID.

movie.ids.crunchyroll

string

Crunchyroll episode ID.

movie.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

movie.title

string

Example:

"Terminator 3: Rise of the Machines"

movie.year

integer

Example:

2003

show

object

Standard show object. May include nested seasons/episodes for partial sync.

Hide child attributes

show.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

show.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

show.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

show.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

show.ids.tmdb

string

TMDb ID.

Example:

"296"

show.ids.tvdb

TVDB ID or slug.

Example:

153021

show.ids.mal

string

MyAnimeList ID.

Example:

"4246"

show.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

show.ids.anilist

string

AniList ID.

Example:

"21"

show.ids.kitsu

string

Kitsu ID.

Example:

"12"

show.ids.anisearch

string

aniSearch ID.

Example:

"2227"

show.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

show.ids.livechart

string

LiveChart ID.

Example:

"321"

show.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

show.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

show.ids.hulu

string

Hulu episode ID.

show.ids.crunchyroll

string

Crunchyroll episode ID.

show.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

show.title

string

Example:

"The Walking Dead"

show.year

integer

Example:

2010

show.seasons

object[]

Hide child attributes

show.seasons.number

integer

show.seasons.episodes

object[]

Hide child attributes

show.seasons.episodes.season

integer

Required range: x >= 0

Example:

1

show.seasons.episodes.number

integer

Required range: x >= 1

Example:

2

show.seasons.episodes.watched_at

string<date-time>

ISO-8601 GMT timestamp.

Example:

"2014-09-01T09:10:11Z"

show.seasons.episodes.ids

object

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

show.seasons.episodes.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

show.seasons.episodes.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

show.seasons.episodes.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

show.seasons.episodes.ids.tmdb

string

TMDb ID.

Example:

"296"

show.seasons.episodes.ids.tvdb

TVDB ID or slug.

Example:

153021

show.seasons.episodes.ids.mal

string

MyAnimeList ID.

Example:

"4246"

show.seasons.episodes.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

show.seasons.episodes.ids.anilist

string

AniList ID.

Example:

"21"

show.seasons.episodes.ids.kitsu

string

Kitsu ID.

Example:

"12"

show.seasons.episodes.ids.anisearch

string

aniSearch ID.

Example:

"2227"

show.seasons.episodes.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

show.seasons.episodes.ids.livechart

string

LiveChart ID.

Example:

"321"

show.seasons.episodes.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

show.seasons.episodes.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

show.seasons.episodes.ids.hulu

string

Hulu episode ID.

show.seasons.episodes.ids.crunchyroll

string

Crunchyroll episode ID.

show.seasons.episodes.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

anime

object

Standard anime object. Like Show, but may include anime_type. Episode numbering follows AniDB.

Hide child attributes

anime.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

anime.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

anime.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

anime.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

anime.ids.tmdb

string

TMDb ID.

Example:

"296"

anime.ids.tvdb

TVDB ID or slug.

Example:

153021

anime.ids.mal

string

MyAnimeList ID.

Example:

"4246"

anime.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

anime.ids.anilist

string

AniList ID.

Example:

"21"

anime.ids.kitsu

string

Kitsu ID.

Example:

"12"

anime.ids.anisearch

string

aniSearch ID.

Example:

"2227"

anime.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

anime.ids.livechart

string

LiveChart ID.

Example:

"321"

anime.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

anime.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

anime.ids.hulu

string

Hulu episode ID.

anime.ids.crunchyroll

string

Crunchyroll episode ID.

anime.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

anime.title

string

Example:

"Attack on Titan"

anime.year

integer

Example:

2013

anime.anime_type

enum<string>

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.

Available options:

tv,

movie,

special,

ova,

ona,

music video

anime.episodes

object[]

Hide child attributes

anime.episodes.season

integer

Required range: x >= 0

Example:

1

anime.episodes.number

integer

Required range: x >= 1

Example:

2

anime.episodes.watched_at

string<date-time>

ISO-8601 GMT timestamp.

Example:

"2014-09-01T09:10:11Z"

anime.episodes.ids

object

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

anime.episodes.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

anime.episodes.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

anime.episodes.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

anime.episodes.ids.tmdb

string

TMDb ID.

Example:

"296"

anime.episodes.ids.tvdb

TVDB ID or slug.

Example:

153021

anime.episodes.ids.mal

string

MyAnimeList ID.

Example:

"4246"

anime.episodes.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

anime.episodes.ids.anilist

string

AniList ID.

Example:

"21"

anime.episodes.ids.kitsu

string

Kitsu ID.

Example:

"12"

anime.episodes.ids.anisearch

string

aniSearch ID.

Example:

"2227"

anime.episodes.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

anime.episodes.ids.livechart

string

LiveChart ID.

Example:

"321"

anime.episodes.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

anime.episodes.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

anime.episodes.ids.hulu

string

Hulu episode ID.

anime.episodes.ids.crunchyroll

string

Crunchyroll episode ID.

anime.episodes.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

episode

object

Episode reference. Use season + number, or ids.

Hide child attributes

episode.season

integer

Required range: x >= 0

Example:

1

episode.number

integer

Required range: x >= 1

Example:

2

episode.watched_at

string<date-time>

ISO-8601 GMT timestamp.

Example:

"2014-09-01T09:10:11Z"

episode.ids

object

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

episode.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

episode.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

episode.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

episode.ids.tmdb

string

TMDb ID.

Example:

"296"

episode.ids.tvdb

TVDB ID or slug.

Example:

153021

episode.ids.mal

string

MyAnimeList ID.

Example:

"4246"

episode.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

episode.ids.anilist

string

AniList ID.

Example:

"21"

episode.ids.kitsu

string

Kitsu ID.

Example:

"12"

episode.ids.anisearch

string

aniSearch ID.

Example:

"2227"

episode.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

episode.ids.livechart

string

LiveChart ID.

Example:

"321"

episode.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

episode.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

episode.ids.hulu

string

Hulu episode ID.

episode.ids.crunchyroll

string

Crunchyroll episode ID.

episode.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

tvdb_season

integer

For anime: original TVDB season number when AniDB mapping differs.

tvdb_number

integer

For anime: original TVDB episode number when AniDB mapping differs.

Pause

Stop

⌘I