# The Numbers — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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 discover comprehensive movie industry data including box office statistics, cast and crew information, and all-time records directly from the-numbers.com. Track daily box office charts and retrieve detailed movie information to stay informed about film performance and historical cinema records.

**Category:** Entertainment | **Website:** [the-numbers.com/](https://the-numbers.com/) | **Docs:** [parse.bot/marketplace/1de62da4-36a3-4487-b949-907d1296773e/the-numbers-com-api](https://parse.bot/marketplace/1de62da4-36a3-4487-b949-907d1296773e/the-numbers-com-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/the-numbers/`
**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 all time box office records

Get all-time box office records

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category: domestic, international, or worldwide |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/the-numbers/get-all-time-box-office-records \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>"}'
```

### Get daily box office chart

Get the daily domestic box office chart for a given date. Returns ranked list of movies with their daily gross, theater count, daily/weekly changes, and cumulative total gross. When no date is given, returns the latest available daily chart.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | No | Date in YYYY/MM/DD format (e.g. '2025/12/25'). If omitted, returns the latest available daily chart. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/the-numbers/get-daily-box-office-chart \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>"}'
```

### Get movie cast and crew

Get cast and crew for a movie

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Movie slug (e.g. 'Scream-7-(2026)') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/the-numbers/get-movie-cast-and-crew \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Get movie details

Get comprehensive details for a movie including box office gross revenue, production budget, synopsis, genre, runtime, and other metadata. The slug can be obtained from search_movies results or daily chart Title_slug field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Movie slug from URL path (e.g. 'Avatar-(2009)', 'Avatar-Fire-and-Ash-(2025)'). Obtainable from search_movies results or daily chart Title_slug field. |

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

### Search movies

Search for movies by title using the site's autocomplete API. Returns up to 10 movie results matching the query, filtered to movies only (excludes franchises). Each result includes title, slug, year, lead cast, and director when available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword or movie title to search for |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/the-numbers/search-movies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

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