> ## 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.
# 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`](/api-reference/simkl/get-all-items): `extended`, `date_from`, `episode_watched_at`, `memos`, `language`. Use `date_from` after [`GET /sync/activities`](/api-reference/simkl/get-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}`](/api-reference/simkl/get-watchlist-ratings) instead.
**Already pulling the full library via [`GET /sync/all-items`](/api-reference/simkl/get-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`](/api-reference/simkl/get-all-items) — prefer that route since it's the documented one. |
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**](/conventions/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).
## OpenAPI
````yaml /openapi.json get /sync/ratings/{type}/{rating}
openapi: 3.1.0
info:
title: Simkl API
version: 1.0.0
description: >-
The **Simkl API** lets you build apps that track Movies, TV Shows, and Anime
— scrobble playback, sync watch history, and pull rich metadata.
All requests use HTTPS and return JSON. The base URL is
`https://api.simkl.com`.
**Every request needs three URL parameters and a `User-Agent` header:**
```
/endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app&app-version=1.0
```
See [Headers and required parameters](/conventions/headers) for the full
reference. Endpoints that read or modify a user's data also need an
`Authorization: Bearer ` header — see [OAuth
2.0](/api-reference/oauth) or the [PIN flow](/api-reference/pin).
> ⚠️ **About the auto-rendered cURL examples on each endpoint page:** they
omit `?client_id=…&app-name=…&app-version=…` from the URL for brevity. **You
must add them yourself when copy-pasting**, or use the interactive **"Try
it"** playground (it fills them in for you). This is a Mintlify rendering
convention — every Mintlify-built API doc behaves the same way.
**Get started**
- [Quickstart](/quickstart) — first request in 60 seconds
- [API rules](/api-rules) — what's allowed, what isn't
- [Standard media objects](/conventions/standard-media-objects) — the shapes
every endpoint speaks
- [Errors](/conventions/errors) — every status code Simkl returns
contact:
name: Simkl Developer Support
url: https://support.simkl.com
termsOfService: https://simkl.com/about/policies/terms/
license:
name: Simkl API Terms of Use
url: https://simkl.com/about/policies/terms/
x-logo:
url: https://i.simkl.com/img_tv/apiary_logo_api.png
backgroundColor: '#0E5DAB'
altText: Simkl
servers:
- url: https://api.simkl.com
description: Production API
- url: https://data.simkl.in
description: CDN for static, public data files (Calendar + Trending). No auth required.
security:
- clientId: []
- simklApiKey: []
tags:
- name: OAuth 2.0
description: >-
OAuth 2.0 authorization-code flow for web and mobile apps. The user is
redirected to Simkl, signs in, approves your app, and is redirected back
with a `code` you exchange for an `access_token`. Long-lived tokens — no
refresh-token flow needed.
externalDocs:
description: OAuth 2.0 walkthrough
url: https://api.simkl.org/api-reference/oauth
- name: PIN
description: >-
Device flow for TVs, consoles, smart watches, CLI tools — anywhere typing
a URL is hard. Show a 5-character code; user enters it on simkl.com/pin;
you poll for the access token. **No `client_secret` required.**
externalDocs:
description: PIN flow walkthrough
url: https://api.simkl.org/api-reference/pin
- name: Redirect
description: >-
Helper redirects for one-click "mark as watched", trailers, sharing, and
more.
- name: Search
description: Find shows, movies, and anime by ID, text query, file name, or randomly.
externalDocs:
description: Search guide
url: https://api.simkl.org/guides/search
- name: Movies
description: >-
Browse the Simkl movies catalog: details, premieres, top-of-best, and
genre filters.
- name: TV
description: >-
Browse the Simkl TV catalog: details, episodes, what's airing, premieres,
top-of-best, and genre filters.
- name: Anime
description: >-
Browse the Simkl anime catalog: details, episodes, what's airing,
premieres, top-of-best, and genre filters.
- name: Ratings
description: >-
Read Simkl's average community rating, rank, drop rate, and external
ratings (IMDB, MAL) for any item, or for every item in a user's lists.
- name: Scrobble
description: >-
Report real-time playback to Simkl with `start`, `pause`, and `stop`. At ≥
80 % progress Simkl marks the item as watched automatically; below 80 %
the session is saved as a paused playback the user can resume from any
device.
See [Standard media objects](/conventions/standard-media-objects) for the
supported ID keys.
### Supported ID keys
Inside any `ids` object, pass as many of these as you have. Simkl resolves
to the canonical record.
| ID key | Type | Example |
|---|---|---|
| `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. |
| `imdb` | string | `tt1520211` |
| `tmdb` | integer | `76757` (for TV, specify `type`) |
| `tvdb` | int / string | `153021` or `the-walking-dead` |
| `mal` | integer | `4246` (MyAnimeList) |
| `anidb` | integer | `10846`. Specifying just this is enough for anime
lookups. |
| `anilist` | integer | `21` |
| `kitsu` | integer | `12` |
| `anisearch` | integer | `2227` |
| `animeplanet` | string | `one-piece` |
| `livechart` | integer | `321` |
| `letterboxd` | string | `the-truman-show` |
| `netflix` | integer | `70210890` (movie ID) |
| `traktslug` | string | `john-wick-chapter-4-2023` |
> 📖 Full reference: [Standard media
objects](/conventions/standard-media-objects)
externalDocs:
description: Scrobble guide
url: https://api.simkl.org/guides/scrobble
- name: Sync
description: >-
Use Simkl as a cloud backup for the user's watch history and lists
(Watching, Plan to Watch, On Hold, Dropped, Completed). **Always check
[`/sync/activities`](/api-reference/simkl/get-activities) first** and sync
only the lists that have moved.
All write endpoints accept arrays — batch aggressively. See [Standard
media objects](/conventions/standard-media-objects) for the supported ID
keys.
### Supported ID keys
Inside any `ids` object, pass as many of these as you have. Simkl resolves
to the canonical record.
| ID key | Type | Example |
|---|---|---|
| `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. |
| `imdb` | string | `tt1520211` |
| `tmdb` | integer | `76757` (for TV, specify `type`) |
| `tvdb` | int / string | `153021` or `the-walking-dead` |
| `mal` | integer | `4246` (MyAnimeList) |
| `anidb` | integer | `10846`. Specifying just this is enough for anime
lookups. |
| `anilist` | integer | `21` |
| `kitsu` | integer | `12` |
| `anisearch` | integer | `2227` |
| `animeplanet` | string | `one-piece` |
| `livechart` | integer | `321` |
| `letterboxd` | string | `the-truman-show` |
| `netflix` | integer | `70210890` (movie ID) |
| `traktslug` | string | `john-wick-chapter-4-2023` |
> 📖 Full reference: [Standard media
objects](/conventions/standard-media-objects)
externalDocs:
description: Sync guide
url: https://api.simkl.org/guides/sync
- name: Users
description: User profile, settings, and watch statistics.
externalDocs:
description: Simkl API documentation
url: https://api.simkl.org
paths:
/sync/ratings/{type}/{rating}:
get:
tags:
- Sync
summary: Get the user's rated items, filtered by type and rating
description: >-
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`](/api-reference/simkl/get-all-items):
`extended`, `date_from`, `episode_watched_at`, `memos`, `language`. Use
`date_from` after [`GET
/sync/activities`](/api-reference/simkl/get-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}`](/api-reference/simkl/get-watchlist-ratings) instead.
**Already pulling the full library via [`GET
/sync/all-items`](/api-reference/simkl/get-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`](/api-reference/simkl/get-all-items) — prefer
that route since it's the documented one. |
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**](/conventions/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).
operationId: get-user-ratings
parameters:
- $ref: '#/components/parameters/UserRatingsTypeQuery'
- $ref: '#/components/parameters/UserRatingsRatingQuery'
- $ref: '#/components/parameters/DateFromParam'
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
responses:
'200':
$ref: '#/components/responses/UserRatingsListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'412':
$ref: '#/components/responses/ClientIdFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
security:
- clientId: []
bearerAuth: []
- simklApiKey: []
bearerAuth: []
components:
parameters:
UserRatingsTypeQuery:
name: type
in: path
description: >-
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.
schema:
type: string
enum:
- movies
- shows
- anime
example: anime
required: true
UserRatingsRatingQuery:
name: rating
in: path
required: true
schema:
type: string
pattern: ^(10|[1-9])(,(10|[1-9]))*$
description: >-
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`.
Values outside `1`–`10` are accepted by the URL parser but never match a
real rating, so you'll just get an empty response.
example: 8,9,10
DateFromParam:
name: date_from
in: query
required: false
description: >-
ISO-8601 timestamp. Returns only items updated since this time. Use the
value saved from `/sync/activities`.
schema:
type: string
format: date-time
example: '2024-05-01T12:00:00Z'
ClientIdQuery:
name: client_id
in: query
required: true
description: >-
Your **`client_id`** from your [Simkl developer
settings](https://simkl.com/settings/developer/). Required on every
request.
schema:
type: string
example: YOUR_CLIENT_ID
AppNameQuery:
name: app-name
in: query
required: true
description: >-
Short, lowercase identifier for your app (e.g. `plex-scrobbler`,
`kodi-bridge`). Helps Simkl identify which apps are using the API.
schema:
type: string
example: my-app
AppVersionQuery:
name: app-version
in: query
required: true
description: >-
Your app's current version (e.g. `1.0`, `2.4.1`). Helps Simkl debug
issues you report.
schema:
type: string
example: '1.0'
UserAgentHeader:
name: User-Agent
in: header
required: true
description: >-
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)`.
schema:
type: string
example: my-app/1.0
responses:
UserRatingsListResponse:
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
shows:
type: array
items:
type: object
properties:
last_watched_at:
type: string
user_rated_at:
type: string
user_rating:
type: number
status:
type: string
last_watched: {}
next_to_watch:
type: string
show:
type: object
properties:
title:
type: string
year:
type: number
ids:
type: object
properties:
simkl:
type: number
imdb:
type: string
tvdb:
type: string
anime:
type: array
items:
type: object
properties:
last_watched_at:
type: string
user_rated_at:
type: string
user_rating:
type: number
status:
type: string
last_watched:
type: string
next_to_watch: {}
show:
type: object
properties:
title:
type: string
year:
type: number
ids:
type: object
properties:
simkl:
type: number
imdb:
type: string
mal:
type: string
anidb:
type: string
movies:
type: array
items:
type: object
properties:
last_watched_at:
type: string
user_rated_at:
type: string
user_rating:
type: number
status:
type: string
movie:
type: object
properties:
title:
type: string
year:
type: number
ids:
type: object
properties:
simkl:
type: number
imdb:
type: string
tmdb:
type: string
example:
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'
Unauthorized:
description: >-
Missing or invalid user access token. Provide a valid `Authorization:
Bearer ` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: user_token_failed
code: 401
ClientIdFailed:
description: >-
Your `client_id` is missing, wrong, disabled, or has hit a request
limit. Verify in your [developer
settings](https://simkl.com/settings/developer/).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: client_id_failed
code: 412
message: Your client_id is wrong. Try another one
RateLimited:
description: >-
Too many requests in too short a window. Back off and retry with
exponential backoff — see [Rate limits](/resources/rate-limits) for the
playbook.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: rate_limit
code: 429
ServerError:
description: >-
Something is broken on Simkl's side. Retry after a short delay. If it
persists, report on the [Simkl Discord](https://discord.gg/MJsWNE4).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: internal
code: 500
schemas:
ErrorResponse:
type: object
description: >-
Standard error envelope for 4xx and 5xx responses. Branch on `error`
(machine-readable identifier) — `message`, when present, is
human-readable guidance and is **not stable across releases**.
properties:
error:
type: string
description: >-
Machine-readable error identifier. Stable across responses — use
this for programmatic branching in client code. Examples:
`user_token_failed`, `client_id_failed`, `empty_field`,
`wrong_parameter`, `id_err`, `rate_limit`.
example: user_token_failed
code:
type: integer
description: >-
HTTP status code echoed in the body for convenience — same value as
the response status line. Always an integer.
example: 401
message:
type: string
description: >-
Human-readable error guidance. Optional — present on most errors,
but not guaranteed. May reference the specific field or value that
triggered the error. NOT stable; do not parse.
example: Your client_id is wrong. Try another one
required:
- error
- code
securitySchemes:
clientId:
type: apiKey
in: query
name: client_id
description: >-
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](/conventions/headers).
x-default: YOUR_CLIENT_ID
simklApiKey:
type: apiKey
in: header
name: simkl-api-key
description: >-
Optional alias for the `client_id` query parameter. Simkl accepts your
`client_id` either as the `simkl-api-key` request header **or** as the
`?client_id=…` query parameter — pick one. The query-parameter form is
preferred because it makes the request fully self-describing in URL
form.
x-default: YOUR_CLIENT_ID
bearerAuth:
type: http
scheme: bearer
description: >-
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](/authentication).
x-default: YOUR_ACCESS_TOKEN
````