# IMDb Scraper (`dami_studio/imdb-scraper`) Actor

IMDb scraper: turn film, show and people names into IMDb IDs, or paste IMDb links. Each row holds the ID, kind, title or name, category, year, the stars or known-for line, popularity rank, poster and link. About 8 results per search term and no ratings. $2.50 per 1,000 rows.

- **URL**: https://apify.com/dami_studio/imdb-scraper.md
- **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community)
- **Categories:** Integrations, AI, Other
- **Features:** Limited permissions
- **Stats:** 10 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.44 / 1,000 items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

**IMDb scraper for a film, a show or a person, the IMDb ID back**, with the title or name, what kind of
thing it is, the year, the stars or known-for line, the poster or headshot, IMDb's popularity rank
and the imdb.com URL. Paste IMDb links instead and you get exactly those titles or people.

Read this bit before you build on it: this is IMDb's public search, so about 8
results come back per query and there is no page two. No ratings, no vote counts, no genre, no
runtime, no plot. It is very good at turning a name into an ID, which is usually the first thing you
need, and it is the wrong tool for full title metadata.

| | |
|---|---|
| **Input** | Search terms, or IMDb title and name links |
| **Output** | One row per result: IMDb ID, kind, title or name, category, year or run, stars or known-for, popularity rank, image, link |
| **Ceiling** | 1,000 rows per run, but only about 8 per search term |
| **Account needed** | None, and no IMDb API key |
| **Price** | $2.50 per 1,000 rows on the Free plan, a little less on paid plans. The free plan's $5 a month covers about 2,000 |

### 🔍 What IMDb Scraper does

It runs your terms through IMDb's public search. One term in `query`, or a list in `queries`,
or both at once. Every term is searched separately and the rows are merged and deduplicated on IMDb
ID, so `inception` and `the matrix` in one run come back as one clean list.

That list is the only way past the per-query ceiling. Setting `maxItems` to 200 does not turn one
term into 200 rows, because the index hands out about 8 and offers no pagination. Twenty-five terms
will get you there; one term will not.

Titles and people both come back. `type` narrows it to one of the two.

Links work too. Paste title or name pages into `startUrls` and each one comes back as exactly that
title or person, one row per link. Handy when you already have the pages and want the clean ID, year
and poster in a table.

### 📋 What data you get from each IMDb result

| What you get | Field |
|---|---|
| The IMDb ID, and what kind of thing it is | `id`, `kind` |
| The title, or the person's name | `title` |
| IMDb's own label, such as feature or TV series | `category` |
| Release year, and the run of a series | `year`, `yearRange` |
| The main cast, or what a person is known for | `starsOrKnownFor` |
| IMDb's popularity rank | `rank` |
| Poster or headshot, and the imdb.com page | `image`, `url` |

### ▶️ How to scrape IMDb

1. Open [IMDb Scraper](https://apify.com/dami_studio/imdb-scraper) and click **Try for free**.
2. Type one thing into **Search query**, paste a list into **Multiple queries**, or paste pages into
   **IMDb links**.
3. Set **Result type** if you only want titles or only people.
4. Leave **Max results** alone for a first run, then click **Start**.
5. Download the dataset as JSON, CSV or Excel, or read it from the Apify API.

### 💰 How much does it cost to scrape IMDb?

**$2.50 per 1,000 rows** on the Free plan. Paid plans pay a little less: $2.48 on Starter, $2.46 on Scale and $2.44 on Business. On the free plan, the $5 Apify
gives you each month covers about 2,000 rows.

You pay per row delivered. Duplicates removed across your terms are not charged, diagnostic rows are
not charged, and if nothing is found, no rows are charged. Since a term returns about 8 rows, a
20-term run lands near 160 rows. Set a maximum cost on the run and it stops when it gets there.

### 📥 What you give it

```json
{
  "queries": ["inception", "the matrix", "arrival"],
  "type": "titles",
  "maxItems": 50
}
```

| Field | Default | What it is |
|---|---|---|
| `query` | none, the form starts with `breaking bad` | A single thing to search for, a film, a show or a person. An API call has to send its own. |
| `queries` | empty list | Several terms in one run, searched one request each, merged and deduplicated by IMDb ID. Set this and `query` together and all of them are searched. |
| `startUrls` | none | IMDb title or name pages, such as `https://www.imdb.com/title/tt0903747/`, or bare IDs like `tt0903747`. One row per link, exactly the title or person it points to. Lists, charts, company and search pages are refused before anything is read. |
| `type` | `all` | `all` keeps titles and people. `titles` keeps IDs starting `tt`. `people` keeps IDs starting `nm`. Links are not filtered by it. |
| `maxItems` | `50` | 1 to 1,000, counted after deduplication across every term. Ask for more than exists and you get what exists. |
| `notionConnector` | none | Optional. Writes one Notion page per row when the run finishes. |
| `notionParentId` | none | Optional. The Notion data source to write into. Leave it empty and the pages land privately in your workspace. |
| `proxyConfiguration` | off | Optional network settings. A normal run does not need them. |

Send none of `query`, `queries` or `startUrls` and the run returns a `BAD_INPUT` row instead of
results.

### 📤 What you get back

A real row from a run on 2 October 2026, with the poster URL cut short:

```json
{
  "ok": true,
  "id": "tt0903747",
  "kind": "title",
  "title": "Breaking Bad",
  "category": "TV series",
  "year": 2008,
  "yearRange": "2008-2013",
  "starsOrKnownFor": "Bryan Cranston, Aaron Paul",
  "rank": 40,
  "image": "https://m.media-amazon.com/images/M/MV5BMzU5ZGYzNmQt...jpg",
  "url": "https://www.imdb.com/title/tt0903747/"
}
```

| Field | How to read it |
|---|---|
| `id` | The IMDb ID, and the reason most people run this. `tt` for titles, `nm` for people. |
| `kind` | `title` or `person`, worked out from the ID prefix. |
| `category` | IMDb's own label, such as `feature`, `TV series` or `video game`. `null` for people. |
| `year`, `yearRange` | Release year, and the run span for a series like `2008-2013`. `null` where neither applies. |
| `rank` | IMDb's popularity rank. Lower is more popular, and it moves from week to week. |
| `image` | Poster or headshot. `null` when IMDb has none. |
| `url` | The imdb.com page of the title or person. |

### 🧾 Reading the output

Two kinds of row land in your dataset.

| Row | How to spot it | Billed |
|---|---|---|
| A result | `ok: true` and an `id` | yes |
| A diagnostic | `ok: false` and an `errorCode` | no |

| Code | What it means |
|---|---|
| `BAD_INPUT` | None of `query`, `queries` or `startUrls` was set, or a link was not an IMDb title or name page. Nothing was searched and no rows were charged. |
| `NO_RESULTS` | The search ran but `type` removed everything it found. Try `type: "all"`. |
| `NOT_FOUND` | A link's ID is not in IMDb's index, so that link has no row of its own. The row carries the `link` and `id`. |
| `TIME_LIMIT` | The run got close to its time limit and stopped early. Every result delivered before that is in your dataset; give the run more time, or send fewer terms and links, to get the rest. If none came back at all, the run is marked as failed. |

Other diagnostics carry their own `errorCode` in the same shape. One thing to know about multi-term
runs: if some terms work and others fail, the failures show up in the run log rather than as rows,
so compare the row count against the number of terms you sent.

### 💡 What people use it for

- Turning a spreadsheet of film or show names into IMDb IDs, so the rest of a pipeline has a key to
  join on.
- Checking that a title people typed by hand actually exists, and catching the ones that matched
  nothing.
- Getting the poster or headshot link for a set of titles or actors.
- Ranking a shortlist by `rank` to see which of them anyone is actually looking up.

### 🚧 What it does not do

- **No ratings, vote counts, genres, runtime, plot or full cast.** Those live on the title page,
  which this does not read.
- **About 8 rows per query, and no second page.** More rows means more terms, not a bigger
  `maxItems`.
- **`type` filters on the ID prefix only.** It is not a search-side filter, so narrowing can empty a
  run that did find things.
- **No companies, franchises or IMDb guide pages.** IMDb's search sometimes lists a franchise or
  one of its own guides next to the films. Those are left out and never charged, so a term can come
  back with 6 or 7 rows instead of 8.
- **Search ranking is IMDb's.** This actor does not re-order what comes back.
- **No watchlists, no reviews, no box office.**
- It is not an official IMDb tool. Dami's Studio is independent and is not affiliated with or endorsed by IMDb, 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 | This one |
| Critic and audience scores for a film or show | [Rotten Tomatoes Scraper](https://apify.com/dami_studio/rotten-tomatoes-scraper) |
| TV shows, full episode lists and main cast | [TV Show Scraper](https://apify.com/dami_studio/tvmaze-scraper) |
| Artists, releases, recordings and labels, with their MBIDs | [MusicBrainz Scraper](https://apify.com/dami_studio/musicbrainz-scraper) |
| Steam games, store details and player reviews | [Steam Scraper](https://apify.com/dami_studio/steam-scraper) |
| Goodreads ratings and rating counts for books | [Goodreads Books Scraper](https://apify.com/dami_studio/goodreads-books-scraper) |
| Wikidata Q-ids and claims for the same people and works | [Wikidata Scraper](https://apify.com/dami_studio/wikidata-scraper) |

### ❓ Questions people ask

#### Can I get a film's IMDb rating out of this?

No. IMDb's public search does not carry ratings, and neither does this actor. For a
critic and audience score, look at the Rotten Tomatoes row in the table above.

#### Why did I only get 8 rows?

That is the ceiling per term. Put more terms into `queries`.

#### Do repeated terms cost me twice?

No. Terms that differ only in capitalisation are searched once, and identical IDs across terms are
merged before anything is charged.

#### Can I search people and titles at once?

Yes, that is what `type: "all"` does. It is the default.

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

The [API tab](https://apify.com/dami_studio/imdb-scraper/api/python) has code for Python, JavaScript and the CLI. MCP
clients like Claude and ChatGPT use `https://mcp.apify.com/?tools=fetch-actor-details,dami_studio/imdb-scraper`;
coding assistants can load [our skill
file](https://api.apify.com/v2/key-value-stores/BTBHU3DdiuoF4JOsK/records/apify-finance-sports-entertainment-SKILL.md).
All three bill your Apify account at the same price.

#### Is scraping IMDb search results legal?

These are public search results. They can still describe real people, which GDPR and similar laws
cover, so have a reason for collecting them. Apify's write-up on
[the legality of web scraping](https://blog.apify.com/is-web-scraping-legal/) is a good starting
point, and we are not lawyers.

### 🆘 If something breaks

Open the **Issues** tab on the actor page. Send the terms you searched and the run ID. The
`errorCode` on the diagnostic row usually names the problem on its own.

# Actor input Schema

## `query` (type: `string`):

A single thing to search IMDb for, a movie, TV show or person name, e.g. "breaking bad" or "tom hanks". For several searches at once, use the "queries" field below instead (or as well).

## `queries` (type: `array`):

Run several searches in one go, one request per term, results merged and de-duplicated by IMDb id. Use this to get more than the ~8 results a single query returns (IMDb's search has no second page). Example: \["inception", "the matrix"]. If both "query" and "queries" are set, all are searched.

## `startUrls` (type: `array`):

Title or name pages copied from IMDb, like https://www.imdb.com/title/tt0903747/ or https://www.imdb.com/name/nm0000158/, or bare ids like tt0903747. Each comes back as exactly that title or person, one row each, and Result type does not filter them. A link IMDb has no entry for gets a free NOT_FOUND row. Lists, charts, company and search pages are not supported, and the run stops before reading anything if one is in the list.

## `type` (type: `string`):

Which kinds of results to keep: "all" (titles and people), "titles" (movies/shows only, IMDb ids starting tt), or "people" (cast/crew only, ids starting nm).

## `maxItems` (type: `integer`):

Maximum number of de-duplicated rows to return across all queries. NOTE: a single query returns a fixed ~8 results (IMDb's search has no second page); to get more, add more terms to "queries". If maxItems exceeds what's available, the actor just returns what it found.

## `notionConnector` (type: `string`):

Optional. Write each item as a page into your Notion when the run finishes. Authorize a Notion connector once in Settings → API & Integrations → MCP connectors, then pick it here. Leave empty to skip (default), results are always saved to the dataset regardless.

## `notionParentId` (type: `string`):

Optional. The Notion data source ID of the database to write into (only used if a Notion connector is set). Leave empty to create the pages privately in your workspace instead.

## `proxyConfiguration` (type: `object`):

Optional, and not needed for a normal run. Your own proxy servers are used exactly as given.

## Actor input object example

```json
{
  "query": "breaking bad",
  "queries": [],
  "type": "all",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Scraped rows are stored in the default dataset (one row per result). Blocked/empty/error runs return a single uncharged diagnostic row instead.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "breaking bad"
};

// Run the Actor and wait for it to finish
const run = await client.actor("dami_studio/imdb-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "breaking bad" }

# Run the Actor and wait for it to finish
run = client.actor("dami_studio/imdb-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "breaking bad"
}' |
apify call dami_studio/imdb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dami_studio/imdb-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zzLRlLMSAcfTDIYOS/builds/DLKyKtpHM1QOWNqJk/openapi.json