Get a user's watch statistics

curl --request POST \
  --url 'https://api.simkl.com/users/{user_id}/stats?client_id=' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

import requests

url = "https://api.simkl.com/users/{user_id}/stats?client_id="

payload = {}
headers = {
    "User-Agent": "<user-agent>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'User-Agent': '<user-agent>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

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

const options = {
  method: 'POST',
  headers: {'User-Agent': '<user-agent>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

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

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{}")
val request = Request.Builder()
  .url("https://api.simkl.com/users/{user_id}/stats?client_id=")
  .post(body)
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("Content-Type", "application/json")
  .build()

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

import Foundation

let parameters = [] as [String : Any?]

let postData = try JSONSerialization.data(withJSONObject: parameters, options: [])

let url = URL(string: "https://api.simkl.com/users/{user_id}/stats")!
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 = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "Content-Type": "application/json"
]
request.httpBody = postData

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

HttpResponse<String> response = Unirest.post("https://api.simkl.com/users/{user_id}/stats?client_id=")
  .header("User-Agent", "<user-agent>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

const url = 'https://api.simkl.com/users/{user_id}/stats?client_id=';
const options = {
  method: 'POST',
  headers: {'User-Agent': '<user-agent>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

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

package main

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

func main() {

	url := "https://api.simkl.com/users/{user_id}/stats?client_id="

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("Content-Type", "application/json")

	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/users/{user_id}/stats?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddJsonBody("{}", false);
var response = await client.PostAsync(request);

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

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/users/{user_id}/stats?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddJsonBody("{}", false);
var response = await client.PostAsync(request);

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/users/{user_id}/stats?client_id=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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/users/{user_id}/stats?client_id=")

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

request = Net::HTTP::Post.new(url)
request["User-Agent"] = '<user-agent>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

$headers=@{}
$headers.Add("User-Agent", "<user-agent>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/users/{user_id}/stats?client_id=' -Method POST -Headers $headers -ContentType 'application/json' -Body '{}'

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/users/{user_id}/stats?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{}");

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/users/{user_id}/stats?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{}");

CURLcode ret = curl_easy_perform(hnd);

{
  "total_mins": 908554,
  "movies": {
    "total_mins": 171969,
    "plantowatch": {
      "mins": 18938,
      "count": 173
    },
    "completed": {
      "mins": 171852,
      "count": 1558
    }
  },
  "tv": {
    "total_mins": 242560,
    "watching": {
      "watched_episodes_count": 2612,
      "count": 41,
      "left_to_watch_episodes": 10276,
      "left_to_watch_mins": 411040,
      "total_episodes_count": 12888
    },
    "hold": {
      "watched_episodes_count": 1157,
      "count": 41,
      "left_to_watch_episodes": 828,
      "left_to_watch_mins": 33120,
      "total_episodes_count": 1985
    },
    "plantowatch": {
      "watched_episodes_count": 243,
      "count": 118,
      "left_to_watch_episodes": 12961,
      "left_to_watch_mins": 518440,
      "total_episodes_count": 13204
    },
    "completed": {
      "watched_episodes_count": 2111,
      "count": 55
    }
  },
  "anime": {
    "total_mins": 494025,
    "watching": {
      "watched_episodes_count": 1747,
      "count": 21,
      "left_to_watch_episodes": 410,
      "left_to_watch_mins": 10250,
      "total_episodes_count": 2157
    },
    "hold": {
      "watched_episodes_count": 97,
      "count": 23,
      "left_to_watch_episodes": 462,
      "left_to_watch_mins": 11550,
      "total_episodes_count": 559
    },
    "plantowatch": {
      "watched_episodes_count": 2324,
      "count": 719,
      "left_to_watch_episodes": 7829,
      "left_to_watch_mins": 195725,
      "total_episodes_count": 10153
    },
    "completed": {
      "watched_episodes_count": 17255,
      "count": 1291
    }
  },
  "watched_last_week": {
    "total_mins": 130,
    "movies_mins": 130,
    "tv_mins": 0,
    "anime_mins": 0
  }
}

{
  "error": "private_profile",
  "code": 403
}

{
  "error": "user_id_failed",
  "code": 404
}

{
  "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 a user's watch statistics

The most expensive call in the Simkl API. Only fire it on an explicit user action.

Stats are computed live on every request — there is no edge cache and no precomputed result cache. The server walks the user’s entire watch history across all three catalogs (movies, TV, anime), looks up the runtime of every completed episode and movie, and aggregates everything from scratch. Response time scales with the size of the user’s library.

OK to call: when the user opens a “My stats” / “Year in review” / profile screen, or taps a refresh button on a stats widget.

Do not call: on app launch, on resume from background, in any polling loop, speculatively to “warm” data, or for every user in a list (e.g. a friends leaderboard — batch via lazy loading). Apps that hammer this endpoint risk rate-limit throttling on the client_id.

Returns aggregate stats for the given user — total movies / shows / anime watched, total time spent, episode counts, last-week activity, and basic profile info.

The user_id must be a positive integer — the numeric Simkl id of the target account. To fetch stats for the authenticated user, call POST /users/settings once at app start and cache account.id, then pass that value here.

Public profiles can be fetched without a bearer token (clientId-only). Private profiles require either a bearer token belonging to the target user, or a connection the target user has granted the requester (otherwise 403 private_profile).

This is POST for historical reasons — there is no request body.

Response shape

{
 "user": {
 "id": 51,
 "name": "username",
 "joined_at": "2018-01-15T00:00:00Z",
 "avatar": "https://simkl.in/avatars/.../user_100.jpg",
 "gender": "Male",
 "loc": "Spain",
 "age": 28,
 "type": "vip"
 },
 "total_mins": 78230,
 "movies": {
 "total_mins": 18000,
 "plantowatch": { "mins": 0, "count": 12 },
 "completed": { "mins": 18000, "count": 200 },
 "dropped": { "mins": 0, "count": 1 }
 },
 "tv": {
 "total_mins": 35000,
 "watching": { "watched_episodes_count": 23, "count": 4, "left_to_watch_episodes": 12, "left_to_watch_mins": 600, "total_episodes_count": 35 }
 },
 "anime": {... },
 "watched_last_week": { "total_mins": 320, "movies_mins": 60, "tv_mins": 200, "anime_mins": 60 }
}

The user block is omitted when the target user has not loaded any data (e.g. brand-new accounts); only total_mins and the per-domain blocks are guaranteed.

Errors

Code	When
`404 user_id_failed`	`user_id` is `0` or any non-positive integer. There is no shortcut for the authenticated user — always pass a real numeric id.
`403 private_profile`	The target user’s profile is private and the requester does not have access.

POST

users

{user_id}

stats

Get a user's watch statistics

curl --request POST \
  --url 'https://api.simkl.com/users/{user_id}/stats?client_id=' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

import requests

url = "https://api.simkl.com/users/{user_id}/stats?client_id="

payload = {}
headers = {
    "User-Agent": "<user-agent>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'User-Agent': '<user-agent>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

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

const options = {
  method: 'POST',
  headers: {'User-Agent': '<user-agent>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

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

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{}")
val request = Request.Builder()
  .url("https://api.simkl.com/users/{user_id}/stats?client_id=")
  .post(body)
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("Content-Type", "application/json")
  .build()

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

import Foundation

let parameters = [] as [String : Any?]

let postData = try JSONSerialization.data(withJSONObject: parameters, options: [])

let url = URL(string: "https://api.simkl.com/users/{user_id}/stats")!
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 = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "Content-Type": "application/json"
]
request.httpBody = postData

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

HttpResponse<String> response = Unirest.post("https://api.simkl.com/users/{user_id}/stats?client_id=")
  .header("User-Agent", "<user-agent>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

const url = 'https://api.simkl.com/users/{user_id}/stats?client_id=';
const options = {
  method: 'POST',
  headers: {'User-Agent': '<user-agent>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

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

package main

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

func main() {

	url := "https://api.simkl.com/users/{user_id}/stats?client_id="

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("Content-Type", "application/json")

	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/users/{user_id}/stats?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddJsonBody("{}", false);
var response = await client.PostAsync(request);

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

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/users/{user_id}/stats?client_id=");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddJsonBody("{}", false);
var response = await client.PostAsync(request);

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/users/{user_id}/stats?client_id=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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/users/{user_id}/stats?client_id=")

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

request = Net::HTTP::Post.new(url)
request["User-Agent"] = '<user-agent>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

$headers=@{}
$headers.Add("User-Agent", "<user-agent>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/users/{user_id}/stats?client_id=' -Method POST -Headers $headers -ContentType 'application/json' -Body '{}'

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/users/{user_id}/stats?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{}");

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/users/{user_id}/stats?client_id=");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{}");

CURLcode ret = curl_easy_perform(hnd);

{
  "total_mins": 908554,
  "movies": {
    "total_mins": 171969,
    "plantowatch": {
      "mins": 18938,
      "count": 173
    },
    "completed": {
      "mins": 171852,
      "count": 1558
    }
  },
  "tv": {
    "total_mins": 242560,
    "watching": {
      "watched_episodes_count": 2612,
      "count": 41,
      "left_to_watch_episodes": 10276,
      "left_to_watch_mins": 411040,
      "total_episodes_count": 12888
    },
    "hold": {
      "watched_episodes_count": 1157,
      "count": 41,
      "left_to_watch_episodes": 828,
      "left_to_watch_mins": 33120,
      "total_episodes_count": 1985
    },
    "plantowatch": {
      "watched_episodes_count": 243,
      "count": 118,
      "left_to_watch_episodes": 12961,
      "left_to_watch_mins": 518440,
      "total_episodes_count": 13204
    },
    "completed": {
      "watched_episodes_count": 2111,
      "count": 55
    }
  },
  "anime": {
    "total_mins": 494025,
    "watching": {
      "watched_episodes_count": 1747,
      "count": 21,
      "left_to_watch_episodes": 410,
      "left_to_watch_mins": 10250,
      "total_episodes_count": 2157
    },
    "hold": {
      "watched_episodes_count": 97,
      "count": 23,
      "left_to_watch_episodes": 462,
      "left_to_watch_mins": 11550,
      "total_episodes_count": 559
    },
    "plantowatch": {
      "watched_episodes_count": 2324,
      "count": 719,
      "left_to_watch_episodes": 7829,
      "left_to_watch_mins": 195725,
      "total_episodes_count": 10153
    },
    "completed": {
      "watched_episodes_count": 17255,
      "count": 1291
    }
  },
  "watched_last_week": {
    "total_mins": 130,
    "movies_mins": 130,
    "tv_mins": 0,
    "anime_mins": 0
  }
}

{
  "error": "private_profile",
  "code": 403
}

{
  "error": "user_id_failed",
  "code": 404
}

{
  "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.

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

user_id

integer

required

Target user's numeric Simkl id (positive integer). For the authenticated user, first call POST /users/settings and pass back account.id. Passing 0 returns 404 user_id_failed.

Required range: x >= 1

Query Parameters

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

Aggregate watch statistics for a user.

user

object

Hide child attributes

user.id

integer

user.name

string

user.joined_at

string<date-time>

user.avatar

string<uri>

user.gender

string

user.loc

string | null

Type 4 null — data not on file in that field's slot. See Null and missing values.

user.age

string

Age in years, pre-formatted as a string like "30 years". Empty string if the user has not set their birthday or has disabled age display. Pre-formatted by the server — clients should display verbatim rather than parsing.

Example:

"30 years"

user.type

enum<string>

Simkl account plan tier. free is the default; pro and vip are paid tiers that unlock higher rate limits and additional features. Some endpoints gate behavior on this value.

Available options:

free,

pro,

vip

total_mins

integer

Total minutes watched across movies, TV, and anime.

movies

object

anime

object

watched_last_week

object

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

Get a user's watch statistics

Response shape

Errors

Authorizations

Headers

Path Parameters

Query Parameters

Response