Get the user's rated items, filtered by type and rating
Returns the items the user has rated themselves — filtered to one type (movies, shows, or anime) and one or more rating values.
Path parameters
| Segment | What to send |
|---|---|
type | movies, shows, or anime. |
rating | A single value 1–10, or a comma-separated list like 8,9,10. |
Example: GET /sync/ratings/movies/9,10 returns every movie the user rated 9 or 10.
Want every rated item in one type?
Pass the full list as a CSV: GET /sync/ratings/movies/1,2,3,4,5,6,7,8,9,10. The response then includes only items the user actually rated (any value from 1 to 10) and skips unrated library items.
Common query parameters
Same as GET /sync/all-items: extended, date_from, episode_watched_at, memos, language. For incremental sync use date_from without the rating segment — see Ratings delta below.
Ratings delta
When rated_at moves in GET /sync/activities, call GET /sync/ratings/{type}?date_from=… — or GET /sync/ratings?date_from=… for every type at once — with the rating segment left off, and date_from set to the top-level all from your saved snapshot.
- You get every item whose rating changed strictly after
date_from, each as its full watchlist entry — the same shape as/sync/all-items. - A row with
user_rating: nullis a rating the user removed. Clear the score you stored. - A rating segment such as
/1,2,3,4,5,6,7,8,9,10keeps only rows with one of those values, so it drops every removal.
A rating-only change never appears in a /sync/all-items delta, so apps that show user_rating need this call. Walkthrough: Ratings come in their own delta.
This is the user’s own 1–10 scores — not the Simkl community average. If you want Simkl’s public ratings for items in the user’s watchlist, use GET /ratings/{type} instead.
Already pulling the full library via GET /sync/all-items? Each item there already carries user_rating (1–10 or null) and user_rated_at. Filter client-side with item.user_rating === 9 instead of calling this endpoint. Use /sync/ratings/{type}/{rating} only when you want the server to do the filtering — typically the first load of a bulk-rating UI that just needs “all my 9s and 10s” without downloading the whole library. A rating-only change never moves an item into a /sync/all-items delta, though — keep cached ratings current with the ratings delta above.
Silent fallbacks (no errors)
The API is forgiving here and won’t return a 400 when you pass something odd — it just returns an empty or unexpected result. Worth knowing so you don’t think the user has no ratings when the URL was actually wrong:
| URL | What you get back |
|---|---|
/sync/ratings/tv_shows/9 (any unrecognized type word) | 200 with cross-type results at rating 9 — the type segment is silently ignored, not validated. The correct word is shows, not tv_shows. |
/sync/ratings/movies/99 (out of range) | 200 {} — the value is accepted but never matches any 1–10 rating. |
/sync/ratings/movies (rating segment omitted) | Without date_from: 200 with the user’s entire movie library, including unrated items (each carries user_rating: null) — the same as GET /sync/all-items/movies, so prefer that route. With date_from it is the ratings delta above. |
Sync guide — full walkthrough
Two-phase model (initial pull → activities-checked delta loop), date_from semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python.
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).
Path Parameters
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.
movies, shows, anime 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 (likeall) returns the user's entire library for that type, including unrated rows withuser_rating: null. Withdate_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.
^(10|[1-9])(,(10|[1-9]))*$Query Parameters
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.
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.