Skip to main content
GET
Get the user's rated items, filtered by type and rating

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

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

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

Path Parameters

type
enum<string>
required

Which media type to return ratings for. Unrecognized values are silently ignored (no 400) and you'll get cross-type results back — see the description's "Silent fallbacks" table.

Available options:
movies,
shows,
anime
rating
string
required

Which rating bucket(s) to return. Accepted forms:

  • A single value 1–10 (e.g. 9).
  • A comma-separated list (e.g. 8,9,10).
  • To get every rated item of this type, pass the full list: 1,2,3,4,5,6,7,8,9,10. This is the only way to scope the response to actually-rated items — omitting the segment or passing a non-digit value (like all) returns the user's entire library for that type, including unrated rows with user_rating: null. With date_from, leaving the segment off is how you get the ratings delta — removed ratings included.

Values outside 1–10 are accepted by the URL parser but never match a real rating, so you'll just get an empty response.

Pattern: ^(10|[1-9])(,(10|[1-9]))*$

Query Parameters

date_from
string<date-time>

ISO-8601 timestamp. Returns only items changed strictly after this time — one stamped exactly at this value is not returned. Pass the top-level all from the /sync/activities response you saved as your snapshot, exactly as returned.

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.

Response

OK

shows
object[]
anime
object[]
movies
object[]