TVmaze Scraper: TV Shows, Episodes & Cast

TVmaze Scraper pulls complete TV series metadata from TVmaze, show details, genres, network or streaming channel, status, rating, artwork, the full episode list with air dates and summaries, and the full cast with character names.

TVmaze is an open, community-maintained TV database with a public API that needs no key and no signup. This Actor calls it directly: no browser, no proxies, no login, no rate-limit games. Episodes and cast are embedded into the same request as the show, so a full series snapshot is one HTTP call.

Agent skill: SKILL.md

https://api.apify.com/v2/key-value-stores/t7YoTxpZEJOWvw4Ug/records/tvmaze-shows-scraper.md

What you get

Output field	Meaning
showId, name, url	TVmaze ID, show title and the public TVmaze page
type, language, genres	Scripted / Reality / Animation, original language, genre list
status	Running, Ended, To Be Determined, In Development
runtime	Episode runtime in minutes (falls back to TVmaze's average when episodes vary)
premiered, ended	First and last air dates
officialSite	The show's own site, when the database has one
network, webChannel	Broadcast network or streaming channel, streaming-only shows have network: null
rating	TVmaze community rating out of 10
summary	Show synopsis as clean plain text, HTML stripped, entities decoded
imageUrl	Full-resolution poster
episodes	Every episode: season, number, name, type, airdate, airstamp, runtime, rating, url, summary
cast	Every cast member: person, character, country, birthday, plus self and voice flags
scrapedAt	Run timestamp

A RUN_SUMMARY record in the key-value store holds per-run counts, shows, episodes and cast members saved, plus any term or ID that failed.

Common use cases

• Build a TV tracking or watchlist app. Air dates and episode numbering come ready to index.
• Enrich a streaming catalogue. Match your titles to TVmaze IDs and pull genres, artwork and cast.
• Media research. Analyse genre mix, network vs streaming split, or run length across a set of shows.
• AI agents and RAG pipelines. Clean plain-text summaries make good retrieval chunks with no HTML cleanup step.
• Recommendation seeds. Cast overlap between shows is a strong, cheap similarity signal.

Quick start

Look up shows by name, best match for each:

{
 "searchTerms": ["Severance", "Breaking Bad"]
}

Exact shows you already know, metadata only:

{
 "showIds": ["44933", "https://www.tvmaze.com/shows/169/breaking-bad"],
 "includeEpisodes": false,
 "includeCast": false
}

Broad discovery, keep every ranked hit per term:

{
 "searchTerms": ["detective", "space"],
 "maxShowsPerTerm": 10,
 "includeEpisodes": false,
 "includeCast": true
}

Input

Field	Type	Default	Notes
searchTerms	array	[]	Show titles. Each is resolved through TVmaze's relevance-ranked search.
showIds	array	[]	Exact TVmaze IDs. Full tvmaze.com/shows/<id>/. URLs are accepted and normalised.
includeEpisodes	boolean	true	Embed the full episode list.
includeCast	boolean	true	Embed the full cast list.
maxShowsPerTerm	integer	1	How many ranked hits to keep per search term. TVmaze returns at most 10. 0 = keep every hit.

At least one of searchTerms or showIds is required, supplying both is fine and the two are merged, so a show reached by both routes is still scraped once. Turning off includeEpisodes and includeCast produces a compact catalogue-style dataset; leaving both on makes each record self-contained.

Output example

{
 "showId": 44933,
 "name": "Severance",
 "type": "Scripted",
 "language": "English",
 "genres": ["Drama", "Science-Fiction", "Mystery"],
 "status": "Running",
 "runtime": 49,
 "premiered": "2022-02-18",
 "ended": null,
 "officialSite": "https://tv.apple.com/show/severance/…",
 "network": null,
 "webChannel": "Apple TV",
 "rating": 7.7,
 "summary": "Mark Scout leads a team at Lumon Industries, whose employees have undergone a severance procedure …",
 "imageUrl": "https://static.tvmaze.com/uploads/images/original_untouched/548/1371406.jpg",
 "url": "https://www.tvmaze.com/shows/44933/severance",
 "episodes": [
 {
 "episodeId": 2238231,
 "season": 1,
 "number": 1,
 "name": "Good News About Hell",
 "type": "regular",
 "airdate": "2022-02-18",
 "airstamp": "2022-02-18T12:00:00+00:00",
 "runtime": 57,
 "rating": 7.2,
 "url": "https://www.tvmaze.com/episodes/2238231/severance-1x01-good-news-about-hell",
 "summary": "Mark is promoted to lead a team who've had their memories surgically divided …"
 }
 ],
 "cast": [
 {
 "personId": 31964,
 "personName": "Adam Scott",
 "personUrl": "https://www.tvmaze.com/people/31964/adam-scott",
 "country": "United States",
 "birthday": "1973-04-03",
 "characterId": 673312,
 "characterName": "Mark Scout",
 "characterUrl": "https://www.tvmaze.com/characters/673312/severance-mark-scout",
 "self": false,
 "voice": false
 }
 ],
 "scrapedAt": "2026-08-06T12:00:00.000Z"
}

API example

curl -X POST "https://api.apify.com/v2/acts/arman-bd~tvmaze-shows-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "searchTerms": ["Severance"],
 "includeEpisodes": true,
 "includeCast": true
 }'

JavaScript example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('arman-bd/tvmaze-shows-scraper').call({
 searchTerms: ['Severance', 'The Bear'],
 includeEpisodes: true,
 includeCast: false,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const show of items) {
 console.log(`${show.name} (${show.premiered}), ${show.episodes.length} episodes on ${show.webChannel ?? show.network}`);
}

Notes

• A missing show doesn't kill the run. A search with no hits, or an ID that does not exist, is recorded in RUN_SUMMARY.failures and the run continues. The Actor only errors out if nothing at all could be scraped.
• Transient errors are retried. 429 and 5xx get three attempts with exponential backoff; a 404 on a specific ID fails fast because retrying it never helps.
• One request per show. Episodes and cast come back as TVmaze embeds on the show call, so scraping a series with 200 episodes is still a single HTTP request.
• Summaries are decoded twice. TVmaze summaries are user-contributed HTML and some arrive already encoded, so entities are decoded before tags are stripped and again afterwards. You get real text, not <p>.
• Network vs web channel. Broadcast shows fill network; streaming originals fill webChannel and leave network null. Read both.
• Public data only. No authentication, no personal data, no access-control bypass.

FAQ

Do I need a TVmaze API key? No. You supply no credentials.

Do I need a proxy? No. Proxy configuration is not required to run this Actor.

Why did my search return the wrong show? TVmaze ranks by relevance and the default keeps only the top hit. Raise maxShowsPerTerm, or pass the exact showIds when you already know them.

Why is runtime different from an episode's runtime? The show-level value is the typical length; TVmaze leaves it null for shows with variable episodes, in which case this Actor falls back to the average runtime. Per-episode runtime is always the exact one.

Are specials and pilots included? Yes, every episode TVmaze holds is returned, with type distinguishing regular, special and insignificant.

Can I schedule it? Yes. Air dates change often, so a nightly run over a watchlist keeps episodes current. Diff on episodeId plus airdate to spot schedule changes.

Can I integrate it with something else? Yes, Apify API, client libraries, webhooks, scheduled runs, dataset exports (JSON/CSV/Excel) or MCP. Output is structured JSON.