thetvdb.com 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.
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'
List TV series from the database with pagination. Returns series sorted by popularity.
| 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, each containing id, name, slug, type, image, first_aired, status, and 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": 848660,
"nbPages": 1000
},
"status": "success"
}
}About the thetvdb.com 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.
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.
- 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 | 250 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.