TV show details

curl --request GET \
  --url https://api.simkl.com/tv/{id} \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'

import requests

url = "https://api.simkl.com/tv/{id}"

headers = {
    "User-Agent": "<user-agent>",
    "simkl-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/tv/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/tv/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/tv/{id}")
  .get()
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("simkl-api-key", "<api-key>")
  .build()

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

import Foundation

let url = URL(string: "https://api.simkl.com/tv/{id}")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "simkl-api-key": "<api-key>"
]

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

const url = 'https://api.simkl.com/tv/{id}';
const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

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

package main

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

func main() {

	url := "https://api.simkl.com/tv/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("simkl-api-key", "<api-key>")

	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/tv/{id}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

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

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/tv/{id}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/tv/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "User-Agent: <user-agent>",
    "simkl-api-key: <api-key>"
  ],
]);

$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/tv/{id}")

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

request = Net::HTTP::Get.new(url)
request["User-Agent"] = '<user-agent>'
request["simkl-api-key"] = '<api-key>'

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

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/tv/{id}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/tv/{id}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "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",
    "traktslug": "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>'

import requests

url = "https://api.simkl.com/tv/{id}"

headers = {
    "User-Agent": "<user-agent>",
    "simkl-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/tv/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/tv/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/tv/{id}")
  .get()
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("simkl-api-key", "<api-key>")
  .build()

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

import Foundation

let url = URL(string: "https://api.simkl.com/tv/{id}")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "simkl-api-key": "<api-key>"
]

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

const url = 'https://api.simkl.com/tv/{id}';
const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

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

package main

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

func main() {

	url := "https://api.simkl.com/tv/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("simkl-api-key", "<api-key>")

	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/tv/{id}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

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

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/tv/{id}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/tv/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "User-Agent: <user-agent>",
    "simkl-api-key: <api-key>"
  ],
]);

$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/tv/{id}")

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

request = Net::HTTP::Get.new(url)
request["User-Agent"] = '<user-agent>'
request["simkl-api-key"] = '<api-key>'

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

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/tv/{id}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/tv/{id}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "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",
    "traktslug": "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

string

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

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

TV show details

Authorizations

Headers

Path Parameters

Query Parameters

Response