Skip to main content
GET
/
users
/
recently-watched-background
/
{user_id}
curl -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/users/recently-watched-background/12345?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
{ "id": 17465, "url": "https://simkl.com/tv/17465/game-of-thrones", "title": "Game of Thrones", "poster": "17/17465posterkey", "fanart": "17/17465fanartkey" }

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

simkl-api-key
string
header
default:YOUR_CLIENT_ID
required

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.

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

Simkl user id which has public privacy settings.

Query Parameters

image
enum<string>

Switches the response mode:

  • Omitted (no image param) → 200 with JSON metadata (id, url, title, poster, fanart).
  • image=poster302 redirect to the poster JPG on simkl.net/posters/.
  • image=fanart302 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.

Available options:
poster,
fanart
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

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.

id
integer
required

Simkl id of the most recently watched item.

Example:

17465

url
string<uri>
required

Canonical simkl.com/<type>/<id>/<slug> URL — drop into a card heading or share button.

Example:

"https://simkl.com/tv/17465/game-of-thrones"

title
string
required

Display title of the most recently watched item.

Example:

"Game of Thrones"

poster
string | null

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.

Example:

"17/17465posterkey"

fanart
string | null

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.

Example:

"17/17465fanartkey"