# IMDb — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and retrieve comprehensive IMDb movie information including ratings, genres, cast, crew, and box office data in one place. Get full cast and crew details alongside plot summaries and financial insights for any movie title.

**Category:** Entertainment | **Website:** [imdb.com/](https://imdb.com/) | **Docs:** [parse.bot/marketplace/e001ed66-d8c4-411a-b0b8-f40800028068/imdb-com-api](https://parse.bot/marketplace/e001ed66-d8c4-411a-b0b8-f40800028068/imdb-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/imdb/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get full cast

Get the complete cast list for a movie with cursor-based pagination support. Use this when you need all cast members beyond what get_movie_details returns. Each page returns up to 50 cast members with a cursor for the next page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Cursor for pagination (from end_cursor of previous response). |
| `limit` | integer | No | Number of cast members per page (max 50). |
| `title_id` | string | Yes | IMDb title ID (e.g., tt0816692). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/imdb/get-full-cast \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"after":"<string>","limit":"<integer>","title_id":"<string>"}'
```

### Get movie details

Get comprehensive movie details including title, plot overview, IMDb rating, genres, cast (with character names), directors, writers, budget, box office, keywords, and more. The cast returned is capped by cast_limit; use get_full_cast for the complete list with pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cast_limit` | integer | No | Maximum number of cast members to return (max 50). |
| `title_id` | string | Yes | IMDb title ID (e.g., tt0816692). The 'tt' prefix is optional. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/imdb/get-movie-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"cast_limit":"<integer>","title_id":"<string>"}'
```

### Get popular movies

Get the most popular movies from IMDb's Movie Meter chart (https://www.imdb.com/chart/moviemeter/). Returns up to 100 movies ranked by current popularity, with title, poster image, rating, release year, genres, languages, plot, runtime, and content rating. Supports cursor-based pagination via the 'after' parameter. Each page returns up to 'limit' movies.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Cursor for pagination (from end_cursor of previous response). |
| `limit` | integer | No | Number of movies per page (max 100). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/imdb/get-popular-movies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"after":"<string>","limit":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.