> ## 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.

# About TV

> Look up TV shows, browse what's airing or premiering, and pull episode lists.

The TV API returns metadata about TV shows in Simkl's catalog. None of these endpoints require an OAuth `token` — a `client_id` is enough.

The `status` field on a show can be `ended`, `tba`, or `airing`.

## Look up a show

Item-level lookups for when you already know which show you want. Both are Cloudflare-cached by Simkl ID — see [Rate limits → Parallel requests](/resources/rate-limits#parallel-requests--when-allowed).

<CardGroup cols={2}>
  <Card title="Show details" icon="circle-info" href="/api-reference/simkl/get-tv-show">
    `GET /tv/{id}` — full record (overview, network, runtime, country, certification, genres, status, first/last-aired dates, total episodes, airs schedule, ratings, posters, fanart, trailers, external IDs, user recommendations).
  </Card>

  <Card title="Episode list" icon="list-ol" href="/api-reference/simkl/get-tv-episodes">
    `GET /tv/episodes/{id}` — every season + episode for a show, with `aired` flags and airdates.
  </Card>
</CardGroup>

If you only have an external ID (IMDb, TMDB, TVDB), resolve it to a Simkl ID via [`GET /redirect`](/api-reference/redirect) first — header-only, Cloudflare-cached, and the canonical resolver.

## Browse & discover

Find shows by what's on now, what's coming, what's top-rated, or by genre / country / network / year.

<CardGroup cols={2}>
  <Card title="Airing" icon="signal-stream" href="/api-reference/simkl/get-tv-airing">
    `GET /tv/airing` — what's airing right now.
  </Card>

  <Card title="Premieres" icon="calendar-day" href="/api-reference/simkl/get-tv-premieres">
    `GET /tv/premieres/{param}` — upcoming season and series premieres.
  </Card>

  <Card title="Best of" icon="trophy" href="/api-reference/simkl/get-best-tv">
    `GET /tv/best/{filter}` — top-rated shows by filter (year, all-time, etc.).
  </Card>

  <Card title="Genres" icon="compass" href="/api-reference/simkl/get-tv-genres">
    `GET /tv/genres/...` — browse by genre, country, network, year.
  </Card>
</CardGroup>

## Pre-built data files (no per-user cost)

Two static JSON resources on the CDN cover the most common "what's hot / what's airing" surfaces without paying any per-user request budget. Send the standard URL parameters and User-Agent; no `Authorization` token needed.

<CardGroup cols={2}>
  <Card title="Trending TV" icon="fire" href="/api-reference/trending">
    `https://data.simkl.in/trending/tv_today.json` + week / month variants, plus Top-100 and Top-500 versions. Refreshed daily. Drives "Most Watched" / "Trending Now" surfaces without polling.
  </Card>

  <Card title="TV airing calendar" icon="calendar" href="/api-reference/calendar">
    `https://data.simkl.in/calendar/tv.json` + per-month archives at `/calendar/{YEAR}/{MONTH}/tv.json`. Updated every 6 hours. Far cheaper than polling `/tv/airing`.
  </Card>
</CardGroup>