Skip to main content
GET
/
tv
/
{id}
TV show details
curl --request GET \
  --url https://api.simkl.com/tv/{id} \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'
{ "title": "Game of Thrones", "year": 2011, "type": "show", "ids": { "simkl": 17465, "slug": "game-of-thrones", "tvdb": "121361", "tvdbslug": "game-of-thrones", "imdb": "tt0944947", "tmdb": "1399", "trakttvslug": "game-of-thrones" }, "rank": 6, "droprate": "1.2%", "poster": "57/5742576cd8f59fcb0", "fanart": "65/651708e80d87bb93", "runtime": 52, "certification": "TV-MA", "country": "US", "overview": "Seven noble families fight for control of the mythical land of Westeros. Friction between the houses leads to full-scale war. All while a very ancient evil awakens in the farthest north.", "genres": [ "Drama", "Fantasy", "Adventure" ], "network": "HBO", "status": "ended", "first_aired": "2011-04-17", "last_aired": "2019-05-19", "airs": { "day": "Sunday", "time": "21:00", "timezone": "America/New_York" }, "total_episodes": 73, "year_start_end": "2011-2019", "ratings": { "simkl": { "rating": 9.1, "votes": 1270 }, "imdb": { "rating": 9.2, "votes": 2287000 } }, "trailers": [ { "name": "Season 1 Trailer", "youtube": "BpJYNVhGf1s", "size": 1080 } ], "users_recommendations": [ { "title": "Breaking Bad", "year": 2008, "poster": "97/978343d5161a724", "type": "tv", "ids": { "simkl": 11121, "slug": "breaking-bad" } }, { "title": "The Walking Dead", "year": 2010, "poster": "16/16913426086fc13", "type": "tv", "ids": { "simkl": 2090, "slug": "the-walking-dead" } } ] }

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

​
id
string
required

Simkl ID for the item. Simkl IDs are stable, unambiguous, and the response is Cloudflare-cached by Simkl ID, so repeat lookups are very fast.

If you only have an external ID (IMDb, TMDB, TVDB, MAL, AniDB, etc.), resolve it to a Simkl ID first via GET /redirect — it returns the Simkl ID in the Location header without a JSON payload, and the follow-up detail call is Cloudflare-cached.

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

OK

Full TV show record returned by GET /tv/{id}. Cloudflare-cached by Simkl ID. The extended query param is a legacy no-op here.

​
title
string
required
​
year
integer
required

First-aired year.

​
type
enum<string>
required

Always show on this endpoint. (The canonical media type for TV records is show — tv is reserved for the URL/route segment.) Live-verified 2026-05-14.

Available options:
show
​
ids
object
required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Example:
{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}
​
rank
integer | null

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

​
droprate
string | null

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

​
poster
string | null

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

​
fanart
string | null

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

​
runtime
integer | null

Episode runtime in minutes (most common length). Type 4 null when unknown.

​
certification
string | null

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

​
country
string | null

Type 4 null — data not on file in that field's slot. See Null and missing values. ISO 3166-1 alpha-2 country of origin.

​
overview
string | null

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

​
genres
string[]
​
network
string | null

Originating network or streamer (e.g. HBO, Netflix). Type 4 null when unknown.

​
status
enum<string> | null

Type 4 null — data not on file in that field's slot. See Null and missing values. Production lifecycle bucket. Closed set of three values; the value is computed from the catalog's Status column plus the next-release timestamp at request time:

  • tba — air date is in the future (next-release timestamp > now)
  • ended — catalog status is Ended
  • airing — everything else (currently releasing, ongoing, hiatus)

Note this is the detail-endpoint status. Listing endpoints (/anime/airing, /anime/best, etc.) use a wider enum from :: (returning series, ongoing, released, canceled, planned, in production, post production, rumored, upcoming) — different shape, document separately.

Available options:
tba,
ended,
airing,
null
​
first_aired
string<date> | null

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

​
last_aired
string<date> | null

Type 4 null — data not on file in that field's slot. See Null and missing values. Date of the most recently aired episode.

​
airs
object

Type 4 null — data not on file in that field's slot. See Null and missing values. Recurring airing schedule (day-of-week, time, timezone). Fields vary; expect at least the broadcasting day for ongoing shows.

​
total_episodes
integer | null

Type 4 null — data not on file in that field's slot. See Null and missing values. Total episode count across all aired and announced seasons.

​
year_start_end
string | null

Type 4 null — data not on file in that field's slot. See Null and missing values. Display-friendly range like 2008-2013, or 2011- for ongoing.

​
ratings
object

Ratings keyed by source. TV shows always carry simkl and imdb.

​
trailers
object[] | null

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

​
users_recommendations
object[]