TheTVDB APIthetvdb.com ↗
Access TheTVDB data via 4 endpoints: search TV series by name, list shows by popularity, get trending series, and fetch full episode listings.
What is the TheTVDB API?
This API exposes 4 endpoints covering TheTVDB's catalog of TV series and episode data. Use the search endpoint to find series by name, the list endpoint to paginate all titles sorted by popularity, trending to retrieve currently popular shows with follower counts, and episodes to pull a complete episode list for any series identified by its slug.
curl -X GET 'https://api.parse.bot/scraper/8dad6e08-58f0-474d-ba39-e162a5572fa1/list?page=0&limit=5' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace thetvdb-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.thetvdb_api import TheTVDB, Show, Episode, TrendingShow
tvdb = TheTVDB()
# Search for a series by name
for show in tvdb.shows.search(query="Breaking Bad", limit=3):
print(show.name, show.slug, show.status, show.network)
# Construct a show by slug and list its episodes
breaking_bad = tvdb.show(slug="breaking-bad")
for episode in breaking_bad.episodes.list(limit=5):
print(episode.code, episode.title, episode.air_date, episode.season)
# Browse trending shows
for trending in tvdb.trendingshows.list(limit=5):
print(trending.name, trending.follower_count, trending.status)
# List popular series from the database
for show in tvdb.shows.list(limit=3):
print(show.name, show.slug, show.image)
List TV series from the database with pagination. Returns series sorted by popularity. Each page contains up to `limit` results; iterate pages from 0 to nbPages-1.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-indexed). Must be less than nbPages in the response. |
| limit | integer | Number of results per page. |
{
"type": "object",
"fields": {
"page": "integer, current page number (0-indexed)",
"items": "array of series objects with id, name, slug, type, image, first_aired, status, network",
"total": "integer, total number of series in the database",
"nbPages": "integer, total number of pages available"
},
"sample": {
"data": {
"page": 0,
"items": [
{
"id": "series-305288",
"name": "Stranger Things",
"slug": "stranger-things",
"type": "series",
"image": "https://artworks.thetvdb.com/banners/posters/305288-4.jpg",
"status": "Ended",
"network": "Netflix",
"first_aired": null
}
],
"total": 711118,
"nbPages": 1000
},
"status": "success"
}
}About the TheTVDB API
Series Discovery
The list endpoint returns a paginated catalog of TV series sorted by popularity. Each item in the items array includes id, name, slug, type, image, first_aired, status, and network. Pagination is 0-indexed via the page parameter; the nbPages and total fields in the response let you determine how many pages exist before iterating. The search endpoint accepts a required query string and returns the same per-series fields, also paginated with page, nbPages, and total.
Trending and Community Signals
The trending endpoint requires no parameters and returns an items array of currently popular series. Each trending item includes id, name, type, first_air_date, status, and follower_count. The follower_count field reflects community engagement on TheTVDB, which can serve as a lightweight popularity signal distinct from view counts or ratings.
Episode Data
The episodes endpoint accepts a slug string (e.g. breaking-bad, game-of-thrones) sourced from the slug field in any list or search result. It returns the full episode list for a series: each episode object contains season, episode_number, code, title, air_date, description, and network. The response also includes episode_count confirming the total number of episodes returned.
The TheTVDB API is a managed, monitored endpoint for thetvdb.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when thetvdb.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official thetvdb.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a TV show tracker by pulling episode air dates and descriptions from the
episodesendpoint. - Populate a content recommendation UI with trending series and their follower counts.
- Index the full TheTVDB catalog for search or filtering using the paginated
listendpoint. - Check a series' current
statusfield to surface only ongoing or ended shows. - Map out a show's season and episode structure using
seasonandepisode_numberfields. - Enrich a media database with
first_aired,network, andimagemetadata from search results. - Monitor community interest shifts over time by polling the
trendingendpoint for follower count changes.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TheTVDB have an official developer API?+
What does the `episodes` endpoint return, and how do I identify the right series?+
season, episode_number, code, title, air_date, description, and network, plus a top-level episode_count. You identify the series by its slug — a URL-friendly string like game-of-thrones — which is included in every item returned by search or list.What happens if I request a page number beyond the available range?+
search and list use 0-indexed pagination. The response includes nbPages indicating the total number of valid pages. Requesting a page value equal to or greater than nbPages will return no items. Always check nbPages before iterating.Does the API return cast, crew, or artwork data for a series?+
Can I filter the `list` or `trending` endpoints by genre, country, or series type?+
list endpoint returns series sorted by popularity with optional pagination parameters only, and trending takes no parameters at all. Filtering by genre, country of origin, or series type is not supported in the current endpoints. You can fork this API on Parse and revise it to add genre or type filtering.