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. Use date_from after GET /sync/activities tells you rated_at has bumped to pull only the newly-changed ratings.
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.
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) | 200 with the user’s entire movie library, including unrated items (each carries user_rating: null). Effectively the same as GET /sync/all-items/movies — prefer that route since it’s the documented one. |
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.
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
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.
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 updated since this time. Use the value saved from /sync/activities.
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.