Skip to main content
GET
/
tv
/
episodes
/
{id}
List episodes for a TV show
curl --request GET \
  --url https://api.simkl.com/tv/episodes/{id} \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'
[ { "title": "Days Gone Bye", "description": "Rick searches for his family after emerging from a coma into a world terrorized by the walking dead. Morgan and Duane, whom he meets along the way, help teach Rick the new rules for survival.", "season": 1, "episode": 1, "type": "episode", "aired": true, "img": "33/33039065126ec2470", "date": "2010-10-31T05:00:00.000Z", "ids": { "simkl_id": 310766 } }, { "title": "Guts", "description": "Rick unknowingly causes a group of survivors to be trapped by walkers. The group dynamic devolves from accusations to violence, as Rick must confront an enemy far more dangerous than the undead.", "season": 1, "episode": 2, "type": "episode", "aired": true, "img": "33/3303806cc83f0ab83", "date": "2010-11-07T05:00:00.000Z", "ids": { "simkl_id": 310768 } } ]

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
integer
required

Simkl ID of the TV show — the parent show's Simkl ID (not an individual episode ID). The endpoint returns the full episode list for that show. Use a Simkl ID directly when you have one — the response is Cloudflare-cached.

If you only have an external ID (IMDb, TMDB, TVDB), resolve it to a Simkl ID first via GET /redirect.

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

Array of episode entries ordered by season then episode. Specials follow the regular episodes and carry type: "special" with no season/episode numbers. An empty array [] is returned for an unknown parent show ID (Type 3 null).

​
title
string
required

Episode title in the response language.

​
type
enum<string>
required

Episode classification. episode for regular numbered episodes, special for one-off content (specials, clip shows, behind-the-scenes, picture dramas, etc.). On TV episode lists specials follow the regular run; on anime listings specials and movies share this enum.

Available options:
episode,
special
​
ids
object
required
​
description
string | null

Synopsis. Type 4 null when no synopsis is on file.

​
season
integer

Season number (1-based).

​
episode
integer

Episode number within the season (1-based).

​
aired
boolean

true if the episode has aired, false if it's still upcoming.

​
img
string | null

Episode still image path. Compose via Images. Type 4 null when no still is on file.

​
date
string | null

Air date+time in the originating network's timezone (e.g. 2011-04-17T21:00:00-05:00). Type 4 null when the schedule isn't on file.