IMDb top charts skill for AI agents

---
name: imdb-top-charts-and-advanced-title-search
description: "Search IMDb movies and TV shows, fetch titles by IMDb ID, browse Top 250 and regional charts, or run an advanced search by genre, year, rating and vote count, with cast, crew and plot details per title. Output fields: title, year, rating, ratingCount, authorRating and more, as JSON rows. Use it for requests like \"IMDb top charts\", or a CSV/JSON export of public IMDb data."
---

# IMDb Top Charts & Advanced Title Search

Search IMDb movies and TV shows, fetch titles by IMDb ID, browse Top 250 and regional charts, or run an advanced search by genre, year, rating and vote count, with cast, crew and plot details per title.

- Actor: https://apify.com/nimbryxo-studio/imdb-top-charts-and-advanced-title-search (ID `nimbryxo-studio~imdb-top-charts-and-advanced-title-search`)
- n8n workflow for the same Actor: https://scraperfinder.com/n8n/imdb-top-charts-and-advanced-title-search/
- Example input: `references/example-input.json`
- Input schema: `references/input-schema.json`
- Output fields: `references/output-fields.json`

## When to use

Use this skill when the user wants:

- IMDb top charts
- a repeatable export of public IMDb data as CSV or JSON

Do not use it for private, login-protected or paywalled data.

## What it returns

One JSON row per result. Columns from the Actor's dataset schema:

- `imdbId`: Imdb Id
- `title`: Title
- `year`: Year
- `rating`: Rating
- `ratingCount`: Rating Count
- `seriesTitle`: Series Title
- `seasonNumber`: Season Number
- `episodeNumber`: Episode Number
- `author`: Author
- `authorRating`: Author Rating
- `genres`: Genres
- `imdbUrl`: Imdb Url

All 14 declared fields: `references/output-fields.json`.

## Inputs

| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| `mode` | string | yes | topRated | What to fetch from IMDb: title search, direct IDs, a chart, the popularity meter, a filtered search, user reviews, or TV episodes. |
| `searchQuery` | string | no |  | Free-text title search, e.g. 'inception' or 'breaking bad'. Used in search mode. |
| `imdbIds` | array | no | [] | IMDb title IDs (e.g. tt0111161) or title URLs. Used by byId, reviews and episodes modes. In episodes mode, pass TV series IDs. |
| `reviewSortBy` | string | no | HELPFULNESS_SCORE | How to order reviews in reviews mode. |
| `reviewSortOrder` | string | no | DESC | Ascending or descending order for the review sort. |
| `excludeSpoilers` | boolean | no | false | Skip reviews flagged as containing spoilers. |
| `titleType` | string | no |  | Restrict results to one content type. Used in search, popular and advanced modes. |
| `genres` | array | no | [] | Filter by genres, e.g. Drama, Thriller, Sci-Fi. Multiple genres are combined with AND. Used in search and advanced modes. |
| `languages` | array | no | [] | Filter by spoken-language codes, e.g. en, fr, hi, ta. Multiple languages are combined with OR. Used in search and advanced modes. |
| `countries` | array | no | [] | Filter by country-of-origin codes, e.g. US, GB, IN, JP. Multiple countries are combined with OR. Used in search and advanced modes. |
| `runtimeMin` | integer | no |  | Only include titles at least this many minutes long. Used in search and advanced modes. |
| `runtimeMax` | integer | no |  | Only include titles at most this many minutes long. Used in search and advanced modes. |
| `yearMin` | integer | no |  | Include only titles released on or after this year. |
| `yearMax` | integer | no |  | Include only titles released on or before this year. |

6 more optional fields on the Actor's Input tab.

Example (`references/example-input.json`):

```json
{
  "searchQuery": "inception",
  "maxItems": 25,
  "mode": "topRated"
}
```

The input passes the Actor's input schema (checked at every publish). First run: `maxItems` = 25, small enough for the 300-second sync wait; raise it once the rows look right.

## Run it

Set `APIFY_TOKEN`, then call the synchronous endpoint for small and medium runs (it waits up to 300 seconds):

```bash
curl -s -X POST "https://api.apify.com/v2/acts/nimbryxo-studio~imdb-top-charts-and-advanced-title-search/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @references/example-input.json > output.json
```

Or with Node 18+: `node scripts/run.mjs [input.json]`.

For large runs, start an async run and read its dataset when it finishes:

```bash
RUN=$(curl -s -X POST "https://api.apify.com/v2/acts/nimbryxo-studio~imdb-top-charts-and-advanced-title-search/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d @references/example-input.json)
RUN_ID=$(echo "$RUN" | jq -r '.data.id'); DATASET=$(echo "$RUN" | jq -r '.data.defaultDatasetId')
curl -s "https://api.apify.com/v2/actor-runs/$RUN_ID?waitForFinish=60" -H "Authorization: Bearer $APIFY_TOKEN" | jq -r '.data.status'
curl -s "https://api.apify.com/v2/datasets/$DATASET/items?format=json" -H "Authorization: Bearer $APIFY_TOKEN" > output.json
```

## Cost and limits

- Apify bills the Actor's usage on your account; the Actor's Pricing tab shows the current price.
- Keep the limit in the input small for a first run.

## Guardrails

- Public data only. Do not pass cookies, sessions or private account data.
- Do not use the output for spam, harassment or unlawful discrimination.
- Check the target site's terms and local law before running at scale.