# IMDb API scraper — movie & TV ratings, vote counts, Top 250 charts, cast, crew and people data: search IMDb for any film, series or person and pull the IMDb user rating, number of votes, release year, runtime, genres, certificate, plot, full cast & characters, directors, writers, episode lists with per-episode ratings, actor/director filmographies, the IMDb Top 250 / Most Popular charts, paginated user reviews, trailers & video clips, photo galleries, awards & nominations, trivia, keywords, parental guide, full cast & crew by department, and 'what's new' lists (coming-soon, weekend box-office, trending) — by IMDb id (tt… / nm…), no API key required

> Search IMDb for movies, TV shows and people by name. Uses IMDb's own type-ahead, so one query returns titles AND people mixed, each with its IMDb id (tt…/nm…), a subtitle, poster image, popularity rank and (for titles) type and year. Use the returned id with the `title`, `person` or `episodes` actions.
> ReefAPI engine `imdb` · 13 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/imdb/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /imdb/v1/search — 1 credit
Search IMDb for movies, TV shows and people by name. Uses IMDb's own type-ahead, so one query returns titles AND people mixed, each with its IMDb id (tt…/nm…), a subtitle, poster image, popularity rank and (for titles) type and year. Use the returned id with the `title`, `person` or `episodes` actions.

**Parameters:**
- `query` (string, required) — What to look for — a movie/show title or a person's name ('the matrix', 'tom hanks', 'breaking bad', 'nolan').
- `kind` (enum, optional, default "all") — Filter the results to titles only, people only, or both (default both). [one of: all, title, name]

**Returns:** results[]{id, kind(title|name), label, subtitle, image, rank, title_type, year}

**Example request body:**
```json
{
  "query": "the matrix"
}
```

### POST /imdb/v1/title — 1 credit
Full IMDb title card for one movie or TV show by its tt… id: IMDb user rating and vote count, year(s), runtime, genres, certificate, plot, countries, languages, directors, writers, top cast with character names, poster and popularity rank. For series it also returns the total episode count.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.

**Returns:** title{id, title, original_title, type, is_series, year, end_year, release_date, runtime_minutes, rating, vote_count, certificate, genres[], plot, image, popularity_rank, countries[], languages[], directors[], writers[], cast[]{id,name,characters[]}, cast_total, episode_count}

**Example request body:**
```json
{
  "imdb_id": "tt0133093"
}
```

### POST /imdb/v1/person — 1 credit
Full IMDb name card for one person by their nm… id: biography, birth/death dates, birthplace, professions, IMDb popularity rank, their best-known titles and a paginated filmography (each credit with the title, year, IMDb rating, the job and — for acting credits — the character played).

**Parameters:**
- `imdb_id` (string, required) — IMDb name id — the 'nm…' in an IMDb person URL (nm0000158 = Tom Hanks). Get one from the `search` action.
- `role` (enum, optional, default "all") — Filter the filmography to one job category (default all). [one of: all, actor, actress, director, writer, producer, self]
- `limit` (integer, optional, default 25) — How many filmography credits to return (1-250, newest first). filmography_total reports the full count.

**Returns:** person{id, name, image, bio, birth_date, death_date, birth_location, professions[], popularity_rank, known_for[], filmography[]{id,title,year,rating,type,job,characters[]}, filmography_total}

**Example request body:**
```json
{
  "imdb_id": "nm0000158"
}
```

### POST /imdb/v1/episodes — 1 credit
Episode list for a TV series by its tt… id, with each episode's IMDb rating, vote count, air date, season/episode number and plot. Page one season at a time with `season`; meta lists every available season number and the total episode count.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `season` (integer, optional) — Season number to list (e.g. 1). Omit to get the first season; meta.seasons lists all available seasons.
- `limit` (integer, optional, default 50) — Max episodes to return for the season (1-250).

**Returns:** episodes[]{id, title, season, episode, rating, vote_count, air_date, plot} + meta{seasons[], total_episodes, season}

**Example request body:**
```json
{
  "imdb_id": "tt0903747",
  "season": 1
}
```

### POST /imdb/v1/charts — 1 credit
An IMDb chart: the Top 250 movies, Top 250 TV, Bottom 100, or a Most-Popular / Top-Rated meter board. Returns ranked titles with their IMDb chart rating, vote count, year, type and poster.

**Parameters:**
- `chart` (enum, optional, default "top_250") — Which IMDb chart to return (default top_250). [one of: top_250, top_250_tv, top_250_english, top_250_india, bottom_100, most_popular_movies, most_popular_tv, top_rated_movies, top_rated_tv, lowest_rated_movies, top_rated_english, top_rated_indian]
- `limit` (integer, optional, default 50) — How many ranked entries to return (1-250).

**Returns:** results[]{rank, id, title, year, type, rating, vote_count, image}

**Example request body:**
```json
{
  "chart": "top_250",
  "limit": 10
}
```

### POST /imdb/v1/reviews — 1 credit
User reviews for a movie or TV show by its tt… id — the full IMDb review text plus the reviewer's star rating, headline, date, spoiler flag and helpful up/down votes. Cursor-paginated: pass the returned `next_cursor` back as `cursor` to walk through every review (titles can have thousands). meta.total reports the full review count.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `sort` (enum, optional, default "helpful") — Order reviews by helpfulness, date, rating or total votes (default helpful). [one of: helpful, recent, rating, votes]
- `cursor` (string, optional) — Pagination cursor from a previous call's meta.next_cursor. Omit for the first page.
- `limit` (integer, optional, default 25) — Reviews per page (1-100). Page with `cursor`.

**Returns:** reviews[]{id, author, rating, title, text, date, helpful_up, helpful_down, spoiler} + meta{total, next_cursor, has_more}

**Example request body:**
```json
{
  "imdb_id": "tt0133093",
  "limit": 5
}
```

### POST /imdb/v1/videos — 1 credit
Trailers and video clips for a movie or TV show by its tt… id, each with a playable MP4 URL (multiple qualities), title, type (Trailer/Clip/Featurette), runtime, description and thumbnail. Note: playback URLs are IMDb-signed and time-limited.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `limit` (integer, optional, default 25) — Max videos to return (1-100).

**Returns:** videos[]{id, name, type, runtime_seconds, description, thumbnail, playback_urls[]{quality,url,mime_type,definition}} + meta{total}

**Example request body:**
```json
{
  "imdb_id": "tt0133093",
  "limit": 5
}
```

### POST /imdb/v1/photos — 1 credit
Image gallery for a movie or TV show by its tt… id — posters, stills and event photos with full-resolution URLs, dimensions and captions. Cursor-paginated: pass the returned `next_cursor` back as `cursor`. meta.total reports the gallery size.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `cursor` (string, optional) — Pagination cursor from a previous call's meta.next_cursor. Omit for the first page.
- `limit` (integer, optional, default 30) — Photos per page (1-100). Page with `cursor`.

**Returns:** photos[]{id, url, width, height, caption} + meta{total, next_cursor, has_more}

**Example request body:**
```json
{
  "imdb_id": "tt0133093",
  "limit": 5
}
```

### POST /imdb/v1/awards — 1 credit
Awards and nominations for a movie or TV show by its tt… id — Oscars, Golden Globes, BAFTAs, Emmys and more, each with the event, year, category, win/nomination flag and the people nominated. Cursor-paginated; meta.total reports the full count.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `cursor` (string, optional) — Pagination cursor from a previous call's meta.next_cursor. Omit for the first page.
- `limit` (integer, optional, default 30) — Awards per page (1-100). Page with `cursor`.

**Returns:** awards[]{id, is_winner, award, category, event, year, notes} + meta{total, next_cursor, has_more}

**Example request body:**
```json
{
  "imdb_id": "tt0133093",
  "limit": 5
}
```

### POST /imdb/v1/extras — 1 credit
Extra IMDb detail for a movie or TV show by its tt… id in one call: trivia, plot keywords, goofs, memorable quotes, alternate titles (AKAs), country release dates, taglines and the parental guide (Sex/Nudity, Violence, Profanity, etc. with severity and example items). Each section is capped by `limit`; section totals are reported.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `limit` (integer, optional, default 20) — Max items per section (trivia/keywords/goofs/quotes/akas/release_dates/taglines), 1-100.

**Returns:** extras{trivia[], keywords[], goofs[], quotes[], akas[], release_dates[], taglines[], parental_guide[]} + per-section totals in meta.section_totals

**Example request body:**
```json
{
  "imdb_id": "tt0133093",
  "limit": 5
}
```

### POST /imdb/v1/credits — 1 credit
Full cast & crew for a movie or TV show by its tt… id, grouped by department (director, writer, cast, producer, cinematographer, editor, composer, …) — beyond the top-20 cast in `title`. Omit `category` for every department (first N each); pass one `category` to page that department fully with `cursor`.

**Parameters:**
- `imdb_id` (string, required) — IMDb title id — the 'tt…' in an IMDb URL (tt0133093 = The Matrix). Get one from the `search` action.
- `category` (string, optional) — One department id to page fully (e.g. cast, director, writer, producer, cinematographer, editor, composer, casting_director). Omit to get every department grouped.
- `cursor` (string, optional) — Pagination cursor (single-category mode) from a previous call's meta.next_cursor.
- `limit` (integer, optional, default 50) — Members per department (grouped) or per page (single category), 1-250.

**Returns:** departments[]{category, total, members[]{id,name,job,characters[],attributes[]}} (grouped) OR credits[]{...} + meta{category,total,next_cursor,has_more} (single category)

**Example request body:**
```json
{
  "imdb_id": "tt0133093"
}
```

### POST /imdb/v1/person_extras — 1 credit
Extra IMDb detail for a person by their nm… id: their photo gallery (full-res URLs + captions), awards and nominations (with the titles they were for), height and alternate names. Complements `person` (bio + filmography).

**Parameters:**
- `imdb_id` (string, required) — IMDb name id — the 'nm…' in an IMDb person URL (nm0000158 = Tom Hanks). Get one from the `search` action.
- `cursor` (string, optional) — Pagination cursor for awards, from a previous call's meta.next_cursor.
- `limit` (integer, optional, default 25) — Max photos and awards to return (1-100). Awards page with `cursor`.

**Returns:** person_extras{id, name, height_cm, akas[], photos[]{id,url,caption}, awards[]{id,is_winner,award,category,event,year,for_titles[]}} + meta{photos_total, awards_total, next_cursor, has_more}

**Example request body:**
```json
{
  "imdb_id": "nm0634240",
  "limit": 5
}
```

### POST /imdb/v1/whats_new — 1 credit
IMDb's 'what's new' lists: upcoming movies (coming_soon_movies) or TV (coming_soon_tv) with release dates, the weekend box-office top 10 (box_office) with gross earnings, or the currently trending titles (trending). One friendly `list` value picks the board; coming-soon lists are cursor-paginated and region-aware.

**Parameters:**
- `list` (enum, optional, default "coming_soon_movies") — Which 'what's new' list to return (default coming_soon_movies). [one of: coming_soon_movies, coming_soon_tv, box_office, trending]
- `region` (string, optional, default "US") — 2-letter region for coming-soon release dates (e.g. US, GB, DE, IN, TR). Ignored for box_office/trending.
- `cursor` (string, optional) — Pagination cursor (coming-soon lists) from a previous call's meta.next_cursor.
- `limit` (integer, optional, default 25) — How many entries to return (1-100).

**Returns:** results[]{id, title, type, year, release_date, rating, vote_count, weekend_gross, image, genres[]} + meta{list, region, next_cursor, has_more, weekend_start, weekend_end}

**Example request body:**
```json
{
  "list": "box_office"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=imdb
- Human docs page: https://reefapi.com/docs/imdb
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt