Get the user's rated items, filtered by type and rating

curl --request GET \
  --url 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'User-Agent: <user-agent>'

import requests

url = "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id="

headers = {
    "User-Agent": "<user-agent>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', Authorization: 'Bearer <token>'}
};

fetch('https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', Authorization: 'Bearer <token>'}
};

fetch('https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=")
  .get()
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

import Foundation

let url = URL(string: "https://api.simkl.com/sync/ratings/{type}/{rating}")!
var components = URLComponents(url: url, resolvingAgainstBaseURL: true)!
let queryItems: [URLQueryItem] = [
  URLQueryItem(name: "client_id", value: ""),
]
components.queryItems = components.queryItems.map { $0 + queryItems } ?? queryItems

var request = URLRequest(url: components.url!)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "Authorization": "Bearer <token>"
]

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

HttpResponse<String> response = Unirest.get("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=")
  .header("User-Agent", "<user-agent>")
  .header("Authorization", "Bearer <token>")
  .asString();

const url = 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=';
const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', Authorization: 'Bearer <token>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id="

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "User-Agent: <user-agent>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = '<user-agent>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

$headers=@{}
$headers.Add("User-Agent", "<user-agent>")
$headers.Add("Authorization", "Bearer <token>")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=' -Method GET -Headers $headers

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "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"
        }
      }
    }
  ]
}

{
  "error": "user_token_failed",
  "code": 401
}

{
  "error": "client_id_failed",
  "code": 412,
  "message": "Your client_id is wrong. Try another one"
}

{
  "error": "rate_limit",
  "code": 429
}

{
  "error": "internal",
  "code": 500
}

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).

GET

sync

ratings

{type}

{rating}

Get the user's rated items, filtered by type and rating

curl --request GET \
  --url 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'User-Agent: <user-agent>'

import requests

url = "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id="

headers = {
    "User-Agent": "<user-agent>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', Authorization: 'Bearer <token>'}
};

fetch('https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', Authorization: 'Bearer <token>'}
};

fetch('https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=")
  .get()
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

import Foundation

let url = URL(string: "https://api.simkl.com/sync/ratings/{type}/{rating}")!
var components = URLComponents(url: url, resolvingAgainstBaseURL: true)!
let queryItems: [URLQueryItem] = [
  URLQueryItem(name: "client_id", value: ""),
]
components.queryItems = components.queryItems.map { $0 + queryItems } ?? queryItems

var request = URLRequest(url: components.url!)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "Authorization": "Bearer <token>"
]

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

HttpResponse<String> response = Unirest.get("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=")
  .header("User-Agent", "<user-agent>")
  .header("Authorization", "Bearer <token>")
  .asString();

const url = 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=';
const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', Authorization: 'Bearer <token>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id="

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "User-Agent: <user-agent>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = '<user-agent>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

$headers=@{}
$headers.Add("User-Agent", "<user-agent>")
$headers.Add("Authorization", "Bearer <token>")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=' -Method GET -Headers $headers

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/sync/ratings/{type}/{rating}?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "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"
        }
      }
    }
  ]
}

{
  "error": "user_token_failed",
  "code": 401
}

{
  "error": "client_id_failed",
  "code": 412,
  "message": "Your client_id is wrong. Try another one"
}

{
  "error": "rate_limit",
  "code": 429
}

{
  "error": "internal",
  "code": 500
}

Authorizations

client_id

string

query

default:YOUR_CLIENT_ID

required

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.

Authorization

string

header

default:YOUR_ACCESS_TOKEN

required

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

User-Agent

string

required

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

type

enum<string>

required

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.

Available options:

movies,

shows,

anime

rating

string

required

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.

Pattern: ^(10|[1-9])(,(10|[1-9]))*$

Query Parameters

date_from

string<date-time>

ISO-8601 timestamp. Returns only items updated since this time. Use the value saved from /sync/activities.

client_id

string

required

Your client_id from your Simkl developer settings. Required on every request.

app-name

string

required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version

string

required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Response

shows

object[]

Hide child attributes

shows.last_watched_at

string

shows.user_rated_at

string

shows.user_rating

number

shows.status

string

shows.last_watched

any

shows.next_to_watch

string

shows.show

object

Hide child attributes

shows.show.title

string

shows.show.year

number

shows.show.ids

object

Hide child attributes

shows.show.ids.simkl

number

shows.show.ids.imdb

string

shows.show.ids.tvdb

string

anime

object[]

Hide child attributes

anime.last_watched_at

string

anime.user_rated_at

string

anime.user_rating

number

anime.status

string

anime.last_watched

string

anime.next_to_watch

any

anime.show

object

Hide child attributes

anime.show.title

string

anime.show.year

number

anime.show.ids

object

Hide child attributes

anime.show.ids.simkl

number

anime.show.ids.imdb

string

anime.show.ids.mal

string

anime.show.ids.anidb

string

movies

object[]

Hide child attributes

movies.last_watched_at

string

movies.user_rated_at

string

movies.user_rating

number

movies.status

string

movies.movie

object

Hide child attributes

movies.movie.title

string

movies.movie.year

number

movies.movie.ids

object

Hide child attributes

movies.movie.ids.simkl

number

movies.movie.ids.imdb

string

movies.movie.ids.tmdb

string

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

Get the user's rated items, filtered by type and rating

Path parameters

Want every rated item in one type?

Common query parameters

Silent fallbacks (no errors)

Sync guide — full walkthrough

Authorizations

Headers

Path Parameters

Query Parameters

Response