TMDB API endpoint
Returns a page of TMDB TV shows from the `category` chart (`popular` by default, or `top_rated`, `airing_today`, `on_the_air`), optionally refined by `sort_by`, `with_genres`, `original_language`, first-air-date bounds `date_from` and `date_to`, rating, votes and runtime. `limit` defaults to 10 (max 20). A filtered page with no matches returns an empty `shows` array.
/tmdb/tv/listReturns TMDB TV charts and filtered TV discovery results. This covers the TV Shows menu pages (popular, airing_today, on_the_air, and top_rated) plus their pagination and browse filters.
Query parameters:
category (optional, default popular). Allowed values: popular, top_rated, airing_today, on_the_air.page (optional, default 1) — 1-based results page.sort_by (optional). Allowed values: popularity.desc, popularity.asc, vote_average.desc, vote_average.asc, first_air_date.desc, first_air_date.asc, name.asc, name.desc.with_genres (optional) — comma- or pipe-separated TV genre ids. Allowed individual values: 10759 (Action & Adventure), 16 (Animation), 35 (Comedy), 80 (Crime), 99 (Documentary), 18 (Drama), 10751 (Family), 10762 (Kids), 9648 (Mystery), 10763 (News), 10764 (Reality), 10765 (Sci-Fi & Fantasy), 10766 (Soap), 10767 (Talk), 10768 (War & Politics), 37 (Western). For the live discovery list, use GET /tmdb/genres.original_language (optional) — two-letter original-language code, for example en.date_from, date_to (optional) — first-air-date bounds in YYYY-MM-DD format.min_rating, max_rating (optional) — TMDB user-rating bounds from 0 to 10.min_votes (optional) — minimum vote count.min_runtime, max_runtime (optional) — runtime bounds in minutes.include_adult (optional, default false).limit (optional, default 10, max 20).Response includes page, has_next_page, and shows[] (id, title, uri). Use id with GET /tmdb/tv/{id} for full detail. A valid filtered page with no matches returns an empty shows array.
| Field | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| id | 20 | |
| title | 20 | “Watch What Happens Live with Andy Cohen” and 19 other values |
| uri | 20 | themoviedb.org |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| category | string | No | TV chart, default popular Allowed values: popular, top_rated, airing_today, on_the_air. | ||
| page | integer | No | 1-based page, default 1 | ||
| sort_by | string | No | Sort order Allowed values: popularity.desc, popularity.asc, vote_average.desc, vote_average.asc, first_air_date.desc, first_air_date.asc, name.asc, name.desc. | ||
| with_genres | string | No | Comma- or pipe-separated TV genre ids: 10759,16,35,80,99,18,10751,10762,9648,10763,10764,10765,10766,10767,10768,37 | 18,10765 | |
| original_language | string | No | Two-letter original-language code | en | |
| date_from | string | No | First-air date lower bound (YYYY-MM-DD) | ||
| date_to | string | No | First-air date upper bound (YYYY-MM-DD) | ||
| min_rating | number | No | Minimum rating, 0-10 | ||
| max_rating | number | No | Maximum rating, 0-10 | ||
| min_votes | integer | No | Minimum vote count | ||
| min_runtime | integer | No | Minimum runtime in minutes | ||
| max_runtime | integer | No | Maximum runtime in minutes | ||
| include_adult | boolean | No | Include adult titles | ||
| limit | integer | No | Max shows, default 10, max 20 | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/tmdb/tv/list?category=popular&page=1&sort_by=popularity.desc&include_adult=true&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"category": "airing_today",
"page": 2,
"has_next_page": true,
"shows": [
{
"id": "1396",
"title": "Breaking Bad",
"uri": "https://www.themoviedb.org/tv/1396-breaking-bad"
}
],
"source_url": "https://www.themoviedb.org/tv/airing-today?page=2"
}
}Request schema
No body schema
Response schema
#/definitions/tmdb.tvListResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | tmdb.TVListResponse | No | ||||
| data.category | string | No | TV chart that was returned: `popular`, `top_rated`, `airing_today` or `on_the_air`. | |||
| data.has_next_page | boolean | No | True when more pages of shows are available. | |||
| data.page | integer | No | Page number returned. | |||
| data.shows | array | No | TV shows on this page, one item per show. | |||
| data.shows[].id | string | No | TMDB id of the movie or TV show. Use it with the movie or TV detail endpoint. | |||
| data.shows[].overview | string | No | Short plot summary. Not filled in for list and chart results. | |||
| data.shows[].poster_url | string | No | URL of the poster image. Not filled in for list and chart results. | |||
| data.shows[].release_date | string | No | Release or first air date. Not filled in for list and chart results. | |||
| data.shows[].title | string | No | Title of the movie or TV show. | |||
| data.shows[].uri | string | No | Link to the title's page on TMDB. | |||
| data.source_url | string | No | URL the data was read from. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/tmdb/tv/list?category=popular&page=1&sort_by=popularity.desc&include_adult=true&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"