API Reference
Trending
Calendar
Redirect
Sync
Changes
Community ratings for items in the user's watchlist
This endpoint returns Simkl’s community ratings (the public average + droprate + vote counts) for every item in the user’s watchlist — not the user’s own 1-10 scores. If you want the user’s own ratings, every GET /sync/all-items response already carries user_rating (1-10 or null) per item — filter that client-side. For server-side filtering by score (e.g. “give me only items I rated 9 or 10”), see GET /sync/ratings/:type/:rating.
Bulk Simkl-rating lookup for items across the user’s watchlist. Useful for ranking the user’s library against community ratings (e.g. “what’s the highest-community-rated movie in my Plan-to-Watch?”).
Returns an array of {id, simkl: {rating, votes, droprate}} for every item in the requested watchlist statuses. Pair with GET /movies/{id} / GET /tv/{id} / GET /anime/{id} (Cloudflare-cached) when you need the full record for any individual item.
Path
| Segment | Values | Notes |
|---|---|---|
type | movies, tv, anime, all | Required. Use /ratings/all to get every type in one response. |
Query
| Param | Required | Notes |
|---|---|---|
user_watchlist | yes | Comma-separated list of watchlist statuses to include. Any of watching, plantowatch, hold, completed, dropped. Use 1 (or any non-empty value) as a shorthand for “all statuses”. Without this param the request silently falls through to a different code path and returns 200 null — always supply it. |
fields | no | Comma-separated extra blocks to include alongside the default simkl block. See the Fields values table below. |
Fields values
fields value | Adds |
|---|---|
simkl (default) | simkl: {rating, votes, droprate} per item. |
ext | imdb: {rating, votes} and/or mal: {rating, votes, rank} (only the providers Simkl has on file for the title). |
rank | rank integer — Simkl’s catalog rank for the item. |
release_status | Human-readable release status (e.g. Ended, Continuing). |
year | release_year integer. |
link | Canonical Simkl URL for the item. |
Combine multiple with commas: fields=simkl,ext,year,rank. Unknown values (including reactions and has_trailer, which are valid on the hidden single-item rating endpoint but not here) are silently ignored.
Auth
Requires Authorization: Bearer <access_token> plus the standard client_id / app-name / app-version URL params.
For the user’s own ratings (the 1-10 scores they’ve assigned), use GET /sync/ratings/:type/:rating instead — that’s the user-rated-by-them endpoint, this one is community-rating-of-everything-in-their-list.
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).
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
Media-type slice. Use all to fetch every type in one response — this is the canonical "I don't care which type" form. The path segment is required because OpenAPI 3.1 does not permit optional path parameters.
movies, tv, anime, all "all"
Query Parameters
all, watching, plantowatch, completed, dropped, hold "1"
- A comma-separated list of additional fields to include in the response.
simkl– returns the Simkl rating and votes.ext– includes external ratings such as IMDB or MAL if available.rank– returns the rank within the Simkl service for that media type (movie, tv, anime).release_status– includes the release status of the item.year– includes the year of release.- Example:
fields=rank,droprate,simkl,ext,year
simkl, ext, rank, release_status, year, link 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
Was this page helpful?