Pulls metadata about the user’s most recently watched item — useful for “Now Watching” widgets, dashboard backgrounds, and embedded user-cards.
PUBLIC endpoint — no access_token required, just your client_id. The target user’s profile must be public; private profiles return 404.
image query param)image | Status | Body | Use case |
|---|---|---|---|
| omitted | 200 | JSON with id, url, title, poster, fanart | Server-side render or custom card layout |
poster | 302 | Empty; Location: https://simkl.net/posters/<key>_0.jpg | Drop the request URL straight into <img src=…> |
fanart | 302 | Empty; Location: https://simkl.net/fanart/<key>_0.jpg | Same — full-bleed background image |
<img> exampleThe ?image= redirect modes are designed for <img src="…"> tags. The browser follows the 302 automatically and renders the JPG — no JSON parsing, no string concatenation, no extra requests:
<!-- Background image (1920×1080-ish) -->
<img src="https://api.simkl.com/users/recently-watched-background/12345?image=fanart&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0">
<!-- Cover poster (vertical) -->
<img src="https://api.simkl.com/users/recently-watched-background/12345?image=poster&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0">
The no-param mode returns the same image keys as the redirect modes — concatenate manually if you want to skip the second round-trip:
{
"id": 17465,
"url": "https://simkl.com/tv/17465/game-of-thrones",
"title": "Game of Thrones",
"poster": "17/17465posterkey",
"fanart": "17/17465fanartkey"
}
Render as https://simkl.net/posters/<poster>_0.jpg / https://simkl.net/fanart/<fanart>_0.jpg.
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.
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.
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).
Simkl user id which has public privacy settings.
Switches the response mode:
image param) → 200 with JSON metadata (id, url, title, poster, fanart).image=poster → 302 redirect to the poster JPG on simkl.net/posters/.image=fanart → 302 redirect to the fanart JPG on simkl.net/fanart/.The two redirect modes are designed to drop straight into an <img src="…"> tag — no JSON parsing or string concatenation needed.
poster, fanart 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.
Returned when ?image= is omitted. JSON metadata about the user's most recently watched item.
Metadata about the user's most recently watched item. Returned by GET /users/recently-watched-background/{user_id} when called WITHOUT the ?image= query param. The poster and fanart fields are catalog image keys (the on-disk path prefix) — to render the actual JPG, either call the same endpoint again with ?image=poster (or ?image=fanart) to get a 302 redirect to the JPG, or concatenate manually: https://simkl.net/posters/<poster>_0.jpg / https://simkl.net/fanart/<fanart>_0.jpg.
Simkl id of the most recently watched item.
17465
Canonical simkl.com/<type>/<id>/<slug> URL — drop into a card heading or share button.
"https://simkl.com/tv/17465/game-of-thrones"
Display title of the most recently watched item.
"Game of Thrones"
Type 4 null — data not on file in that field's slot. See Null and missing values. When present, the poster image key (e.g. "17/17465abcd") — render as https://simkl.net/posters/<this>_0.jpg.
"17/17465posterkey"
Type 4 null — data not on file in that field's slot. See Null and missing values. When present, the fanart image key — render as https://simkl.net/fanart/<this>_0.jpg.
"17/17465fanartkey"
Was this page helpful?