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

TV show details

Full detail record for one TV show — title, overview, year, runtime, country, certification, network, genres, status, first/last-aired dates, total episodes, airs schedule, ratings, posters, fanart, external IDs, trailers, user recommendations. The default response is already complete; no flags needed.

Responses are Cloudflare-cached by Simkl ID, so repeat lookups of popular titles are near-free. Parallel requests against this endpoint are explicitly allowed (see Rate limits → Parallel requests).

Cache invalidation is automatic. When Simkl updates the underlying record (admin edits, automated metadata refresh, image swap, related-titles change, etc.), the corresponding Cloudflare cache entry is purged server-side. The next call to this endpoint returns the fresh data — there’s no TTL to wait out and no client-side cache-busting needed. Your own app-level cache, if any, still has to be invalidated by your client.

Use a Simkl ID for the lookup. If you only have an external ID, resolve it via GET /redirect first.

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

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

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

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

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.

Hide child attributes

ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

ids.imdb

string

IMDb ID.

Example:

"tt0181852"

ids.tmdb

string

TMDb ID.

Example:

"296"

ids.tvdb

TVDB ID or slug.

Example:

153021

ids.mal

string

MyAnimeList ID.

Example:

"4246"

ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

ids.anilist

string

AniList ID.

Example:

"21"

ids.kitsu

string

Kitsu ID.

Example:

"12"

ids.anisearch

string

aniSearch ID.

Example:

"2227"

ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

ids.livechart

string

LiveChart ID.

Example:

"321"

ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

ids.netflix

string

Netflix movie ID.

Example:

"70210890"

ids.hulu

string

Hulu episode ID.

ids.crunchyroll

string

Crunchyroll episode ID.

ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

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 | null

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.

Hide child attributes

ratings.simkl

object

External-source rating.

Hide child attributes

ratings.simkl.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.simkl.votes

integer

Number of votes contributing to the rating.

ratings.imdb

object

External-source rating.

Hide child attributes

ratings.imdb.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.imdb.votes

integer

Number of votes contributing to the rating.

ratings.{key}

object

External-source rating.

Hide child attributes

ratings.{key}.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.{key}.votes

integer

Number of votes contributing to the rating.

trailers

object[] | null

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

Hide child attributes

trailers.name

string | null

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

trailers.youtube

string

trailers.size

integer | null

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

users_recommendations

object[]

Hide child attributes

users_recommendations.title

string

users_recommendations.year

integer | null

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

users_recommendations.poster

string | null

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

users_recommendations.type

string

users_recommendations.ids

object

Hide child attributes

users_recommendations.ids.simkl

integer

users_recommendations.ids.slug

string

About TV

List episodes for a TV show

⌘I