API Reference
Trending
Calendar
Redirect
Sync
Changes
curl --request GET \
--url 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=' \
--header 'Authorization: Bearer <token>' \
--header 'User-Agent: <user-agent>'{
"shows": [
{
"last_watched_at": "2016-09-12T13:00:30.000Z",
"user_rated_at": "2021-06-23T13:19:05.000Z",
"user_rating": 5,
"status": "dropped",
"last_watched": null,
"next_to_watch": "S01E01",
"show": {
"title": "The Last Ship",
"year": 2014,
"ids": {
"simkl": 42040,
"imdb": "tt2402207",
"tvdb": "269533"
}
}
}
],
"anime": [
{
"last_watched_at": "2014-11-06T22:05:52.000Z",
"user_rated_at": "2021-06-23T13:19:05.000Z",
"user_rating": 10,
"status": "completed",
"last_watched": "E148",
"next_to_watch": null,
"show": {
"title": "Hunter x Hunter",
"year": 2011,
"ids": {
"simkl": 40398,
"imdb": "tt2098220",
"mal": "11061",
"anidb": "8550"
}
}
}
],
"movies": [
{
"last_watched_at": "2014-08-16T18:45:20.000Z",
"user_rated_at": "2021-06-23T13:19:05.000Z",
"user_rating": 6,
"status": "completed",
"movie": {
"title": "Maleficent",
"year": 2014,
"ids": {
"simkl": 195258,
"imdb": "tt1587310",
"tmdb": "102651"
}
}
}
]
}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.
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).
curl --request GET \
--url 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=' \
--header 'Authorization: Bearer <token>' \
--header 'User-Agent: <user-agent>'{
"shows": [
{
"last_watched_at": "2016-09-12T13:00:30.000Z",
"user_rated_at": "2021-06-23T13:19:05.000Z",
"user_rating": 5,
"status": "dropped",
"last_watched": null,
"next_to_watch": "S01E01",
"show": {
"title": "The Last Ship",
"year": 2014,
"ids": {
"simkl": 42040,
"imdb": "tt2402207",
"tvdb": "269533"
}
}
}
],
"anime": [
{
"last_watched_at": "2014-11-06T22:05:52.000Z",
"user_rated_at": "2021-06-23T13:19:05.000Z",
"user_rating": 10,
"status": "completed",
"last_watched": "E148",
"next_to_watch": null,
"show": {
"title": "Hunter x Hunter",
"year": 2011,
"ids": {
"simkl": 40398,
"imdb": "tt2098220",
"mal": "11061",
"anidb": "8550"
}
}
}
],
"movies": [
{
"last_watched_at": "2014-08-16T18:45:20.000Z",
"user_rated_at": "2021-06-23T13:19:05.000Z",
"user_rating": 6,
"status": "completed",
"movie": {
"title": "Maleficent",
"year": 2014,
"ids": {
"simkl": 195258,
"imdb": "tt1587310",
"tmdb": "102651"
}
}
}
]
}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.
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.
Response
OK
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
Was this page helpful?