List episodes for a TV show
Returns the full episode list for a Simkl TV show ID. Items include season, episode, title, description, aired (boolean), img, date (timezone-shifted), and ids.simkl_id. Specials appear with type: "special" after the regular episodes, numbered in season 0.
Responses are Cloudflare-cached by Simkl ID, so repeat lookups of popular shows 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 episode list (new episode airs, airdate change, title edit, image swap, etc.), the corresponding Cloudflare cache entry is purged server-side. The next call returns the fresh data — there’s no TTL to wait out. Your own app-level cache, if any, still has to be invalidated by your client.
Use the parent show’s Simkl ID. If you only have an external ID, resolve it via GET /redirect first.
Authorizations
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
Path Parameters
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.
Response
Array of episode entries ordered by season then episode. Specials follow the regular episodes, carry type: "special" and are numbered in season 0 (season: 0, episode: 1, 2, …). Every special is listed, including several with the same title. An empty array [] is returned for an unknown parent show ID (Type 3 null).
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.
episode, special Episode runtime in whole minutes. Type 4 null — null when no runtime is on file for that episode. See Null and missing values.
44
Marks finale episodes so you can badge them:
1— mid-season finale2— season finale3— series finalenull— not a finale. Type 4 null — the episode isn't marked as one. See Null and missing values.
The same values as finale_type in the calendar files. Specials can carry one too. TV only — GET /anime/episodes/{id} doesn't return this field.
1, 2, 3, null 2
Episode still image path. Compose via Images. Type 4 null when no still is on file.