TV Show Scraper - Shows, Episodes & People (TVMaze)

Type a TV show name and get rows back from TVMaze: the rating, genres, network, country, status, premiere date, IMDb id, plain-text summary and poster. Switch modes and the same actor searches TVMaze's people directory by name, or lists every episode of one show, unaired ones included.

Show search is fuzzy, and that cuts both ways. A vague query comes back with loosely related shows, and those rows are charged like any other, so keep maxItems small while you work out the wording.

Input	A show name, a person's name, or a TVMaze show id
Output	One row per show, person or episode. Shows: rating, genres, network, status, dates, IMDb id, summary, poster, and the main cast if you ask
Ceiling	2,000 rows per run
Account needed	None, and no API key
Price	$2.00 per 1,000 rows on the Free plan, a little less on paid plans. The free plan's $5 a month covers about 2,500

🔍 What TV Show Scraper does

One run does one of three jobs, picked with mode.

Shows searches TVMaze by title. Each row carries the rating, genre list, status, runtime, first and last air dates, country, IMDb id and the poster URL. network holds the broadcaster, and for a streaming-only show it holds the streaming service instead, so you never have to read two fields. Turn on includeCast and each show row also lists its main cast: actor, character and TVMaze person id.

People searches the people directory by name and returns id, country, birthday, gender and photo. It is a name lookup, not a cast list. Asking it "who was in Breaking Bad" gets you people called Breaking Bad, which is nobody. For a show's cast, use shows mode with includeCast.

Episodes takes one numeric TVMaze show id and returns the whole run: season, episode number, title, air date, runtime, rating and summary. Episodes with a future air date are included, which is what makes it useful for a release calendar.

Summaries arrive with the HTML tags already stripped out.

📋 What data you get from each TV show

What you get	Field
TVMaze's id, the name and the TVMaze page	id, name, url
Type, language and genres	type, language, genres
Whether it is still running, and its episode length	status, runtime
First and last air dates	premiered, ended
TVMaze's average rating	rating
The broadcaster or streaming service, and the country	network, country
The IMDb id and the official site	imdb, officialSite
The summary as plain text, and the poster	summary, image
The main cast, with includeCast on	cast

▶️ How to scrape TVMaze

1. Open TV Show Scraper and click Try for free.
2. Pick a Mode.
3. Type the show or person into Search query, or put the numeric id into Show id for episodes mode.
4. Set Max items. Ten is plenty while you check the output shape.
5. Click Start, then download the dataset as JSON, CSV, Excel or XML.

💰 How much does it cost to scrape TVMaze?

$2.00 per 1,000 rows on the Free plan. Paid plans pay a little less: $1.98 on Starter, $1.96 on Scale and $1.94 on Business. On the free plan, the $5 Apify gives you each month covers about 2,500 rows. Shows, people and episodes all cost the same, and a show row with its cast costs the same as one without.

Duplicate rows, rows past your maxItems cap and every diagnostic row are not charged. A search that finds nothing returns one uncharged row. Set a maximum cost on the run and it stops when it gets there.

📥 What you give it

{
  "mode": "shows",
  "query": "breaking bad",
  "maxItems": 10
}

Field	Default	What it is
mode	shows	shows, people or episodes.
query	none, the form starts with breaking bad	The show or person name. Ignored in episodes mode. An API call has to send its own.
showId	none	TVMaze's numeric show id, required for episodes mode and ignored otherwise. Run shows first and take it from id.
includeCast	false	Shows mode only. Adds the show's main cast to every show row, at the same price per row. A people or episodes run with it on gets one BAD_INPUT row and nothing is charged.
maxItems	50	1 to 2,000. Rows are deduplicated on id before this cap is applied.
notionConnector	none	Optional. Writes every delivered row into your Notion.
notionParentId	none	Optional. The Notion data source to write into. Leave it empty and the pages are created privately in your workspace.
proxyConfiguration	off	Optional network setting. Off is right for a normal run.

showId is TVMaze's own id, not IMDb's. Breaking Bad is 169 on TVMaze and tt0903747 on IMDb, and putting one where the other belongs gets you a NOT_FOUND row.

📤 What you get back

A real row from a run on 3 October 2026, with the summary cut short:

{
  "ok": true,
  "id": 169,
  "name": "Breaking Bad",
  "type": "Scripted",
  "language": "English",
  "genres": ["Drama", "Crime", "Thriller"],
  "status": "Ended",
  "runtime": 60,
  "premiered": "2008-01-20",
  "ended": "2019-10-11",
  "rating": 9.2,
  "network": "AMC",
  "country": "United States",
  "imdb": "tt0903747",
  "officialSite": "http://www.amc.com/shows/breaking-bad",
  "summary": "Breaking Bad follows protagonist Walter White, a chemistry teacher who lives in New Mexico with his wife and teenage son...",
  "image": "https://static.tvmaze.com/uploads/images/original_untouched/501/1253519.jpg",
  "url": "https://www.tvmaze.com/shows/169/breaking-bad"
}

Field	How to read it
rating	TVMaze's average, or null when too few people have voted. Common on obscure shows and on single episodes.
ended	null while a show is still running. That is how you tell.
network	The broadcaster, or the streaming service for a show that only has one.
imdb	Your join key onto anything else you already hold.
summary	Plain text. Empty summaries come back as "", missing ones as null.
cast	Only with includeCast. A list of {personId, name, character}, one per main cast member. [] when TVMaze lists no cast for the show, null if the cast could not be read.

People rows carry id, name, country, birthday, gender, image and url. Episode rows carry showId, episodeId, name, season, number, airdate, runtime, rating, summary and url.

🧾 Reading the output

Every real row has ok: true. A row that could not be filled has ok: false plus an errorCode, and those are never charged.

Row	How to spot it	Billed
A show, person or episode	ok: true	yes
A diagnostic	ok: false and an errorCode	no

Code	What it means
BAD_INPUT	The mode needs something you did not send: a query for shows or people, a positive whole-number showId for episodes. Also written when includeCast is on outside shows mode.
NOT_FOUND	That showId is not a TVMaze show. Answered straight away, with no retrying.
NO_RESULTS	The search ran and TVMaze had nothing matching.
TIME_LIMIT	The run got close to its time limit and stopped on its own. The rows delivered before that are complete and charged. Give the run more time, or ask for fewer rows, to get the rest.

Anything else that goes wrong lands as one diagnostic row carrying its own code, and the run still finishes rather than failing. The one exception: when the time limit stopped the run before any row came back, it ends as failed, with a TIME_LIMIT row saying so.

One thing to know about the Console's Overview table: it shows a narrow set of columns and drops season and episode number, so an episode list reads as titles with no numbers, and diagnostic rows render blank. Everything is present in the JSON, CSV and Excel exports. Switch the table to all fields, or download the dataset.

💡 What people use it for

• Backfilling a media library that only has titles. Run each one through shows mode and you come out with genres, network, premiere date, poster and an IMDb id to join on.
• Building a release calendar. episodes mode returns the whole run, so filtering airdate to future dates gives you what is still to come.
• Checking whether a show is over. status and a null ended answer it in one row.
• Tagging a back catalogue by genre and country.

From a show name to its release calendar, in three steps:

1. Run shows mode with the title in query and read the number in id.
2. Run episodes mode with that number in showId.
3. Keep the rows whose airdate is after today.

🚧 What it does not do

• The cast is the main cast only, as TVMaze lists it: no guest stars, no crew, nothing per episode. People mode is a name search and cannot answer "who was in this show".
• One showId per run in episodes mode. Several shows means several runs.
• Search reads one page of TVMaze matches, so raising maxItems past that page does nothing in shows and people modes. The cap earns its keep in episodes mode.
• rating is often null where the vote count is too low to publish an average.
• No box office, no streaming availability, no ticket links. TVMaze is a schedule and metadata source, and this returns what it holds.
• Rows are a snapshot. Ratings move and a running show gains episodes. Re-run for fresh numbers.
• It is not an official TVMaze tool. Dami's Studio is independent and is not affiliated with or endorsed by TVMaze, or by any other company named on this page.

🧭 Which film, TV, music or game scraper do you need?

If you want	Use
IMDb IDs for films, shows and people	IMDb Search Scraper
Critic and audience scores for a film or show	Rotten Tomatoes Scraper
TV shows, full episode lists and main cast	This one
Artists, releases, recordings and labels, with their MBIDs	MusicBrainz Scraper
Steam games, store details and player reviews	Steam Scraper
Goodreads ratings and rating counts for books	Goodreads Books Scraper
Wikidata Q-ids and claims for the same people and works	Wikidata Scraper

❓ Questions people ask

Do I need a TVMaze account or key?

No. Nothing to apply for.

How do I find a show id?

Run shows mode with the title and read id off the row. That number goes straight into showId.

Why did my episode list come back with no episode numbers?

The Console's Overview table hides those columns. The numbers are in the data. Download it or switch the table to all fields.

Can I get a show's cast?

Yes. Run shows mode with includeCast on and each show row lists its main cast.

Why did I get shows I did not ask for?

Fuzzy search. A short or vague query pulls in loose matches, and you pay for the rows. Add more of the title.

Can I call it from code or connect it to an AI assistant?

Yes. The API tab has ready-made code for Python, JavaScript and the command line. For Claude, ChatGPT or another MCP client, connect https://mcp.apify.com/?tools=fetch-actor-details,dami_studio/tvmaze-scraper. Either way the run happens on your Apify account at the same price.

Is scraping TVMaze legal?

People rows carry names and birthdays, which data-protection law covers, so have a reason for collecting them. Apify's write-up on the legality of web scraping is a good starting point, and we are not lawyers.

🆘 If something breaks

Open the Issues tab on the actor page. Send the input you used and the run ID. The errorCode on the diagnostic row usually names the problem by itself.