Developer Platform

THE
INSTRUMENT.

Every film as a canonical record. Filter, sort, query, embed. A century of cinema, one REST surface, cursor-paginated and cacheable.

Films

74K+

1920–2026

Version

GA · stable

Latency

p95 < 200ms

edge-cached

Format

REST · JSON

cursor paging

Basehttps://hollywoodmetrics.ai/api/v2

Try it live Endpoint reference

Quick Start

THREE STEPS. ONE OBJECT.

From signed-out visitor to a canonical Film in your code, in under two minutes.

01StepGET A KEY

Subscribe to Producer or Studio and mint a key from the dashboard. Free and Writer tiers are read-only on the site only.

See Plans Open Dashboard

02StepMAKE A REQUEST

Pass your key in the X-API-Key header. Below: fetch The Godfather by IMDb id.

# Fetch a single canonical Film by IMDb id
curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/films/tt0068646"

03StepRECEIVE THE OBJECT

Every endpoint returns the same canonical Film shape: ratings, cast, crew by department, posters, awards, links.

{
  "data": {
    "imdb_id": "tt0068646",
    "title": "The Godfather",
    "year": 1972,
    "runtime": 175,
    "genres": ["Crime", "Drama"],
    "director": "Francis Ford Coppola",
    "ratings": {
      "imdb": 9.2,
      "rt_critics": 97,
      "tmdb": 8.7,
      "master_score": 95.4
    },
    "poster": { "url": "https://...", "source": "gcs" },
    "cast": [ /* top cast members */ ],
    "crew_summary": { /* directing, writing, camera, ... */ }
  }
}

Interactive Playground

RUN A REAL REQUEST.

Edit any parameter, hit Run, watch the canonical JSON come back. No key required for the read-only catalog routes.

Presets

Endpoint

IMDb id

Request URL

GET https://hollywoodmetrics.ai/api/v2/films/tt0068646

Response

Press Run it to see the live response.

The same call, in your stack

# v2 catalog endpoints are public for read-only GETs.
# Add your key once you're past the playground:
curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/films/tt0068646"

Endpoint Reference

EVERY ROUTE. EVERY PARAMETER.

The full v2 surface, curated. The OpenAPI spec stays the source of truth for generated clients.

FILMS

Search the catalog and pull canonical Film objects.

GET/api/v2/films

Filter and sort the full catalog. Returns Film objects in list mode.

Parameters

Name	Type	Description
`q`	string	Free-text search across title, overview, cast, crew, keywords.
`genre`	string	Comma-separated genres (AND match). Case-insensitive.
`decade`	string	e.g. 1990s or 1990.
`year_min`	number	Lower bound on release year.
`year_max`	number	Upper bound on release year.
`min_rating`	number	Minimum IMDb rating.
`min_score`	number	Minimum master score (composite).
`min_votes`	number	Minimum IMDb vote count.
`director`	string	Director name substring.
`actor`	string	Cast name substring.
`language`	string	ISO 639-1 code (e.g. en, fr, ja).
`has_poster`	boolean	true to return only films with a poster.
`sort`	string	field:dir, e.g. master_score:desc, year:asc.
`fields`	string	Comma-separated field projection.
`limit`	number	1–500, default 50.
`cursor`	string	Opaque pagination token from meta.next_cursor.

Response

Envelope { data: Film[], meta: { total, limit, offset, next_cursor, has_more } }. Films include top cast, key crew, posters, ratings, awards, links.

Example

curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/films?genre=Sci-Fi&decade=1980s&min_rating=8.0&limit=10"

GET/api/v2/films/{id}

Full canonical Film by IMDb id, including all cast and full crew by department.

Parameters

Name	Type	Description
`id`req	string	IMDb id, e.g. tt0068646.

Response

Envelope { data: Film }. Detail mode adds full cast, full crew grouped by department, production companies, watch providers, external ids.

Example

curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/films/tt0068646"

GET/api/v2/films/stream

NDJSON stream of the entire catalog, one Film per line.

Parameters

Name	Type	Description
`has_poster`	boolean	Filter to films with a poster.
`fields`	string	Comma-separated field projection (smaller lines).

Response

Newline-delimited JSON. Each line is a canonical Film object. Suitable for one-shot ingestion into a local index or vector store.

Example

curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/films/stream?has_poster=true" \
  | head -n 3

CATALOG

Bulk access to the full Film table as a single download.

GET/api/v2/catalog/snapshot

Signed GCS URL for the gzipped NDJSON catalog snapshot.

Parameters

Name	Type	Description
`format`	string	Pass format=json to get the manifest and signed URL inline. Default is a 302 redirect to the download.

Response

With format=json: { data: { download_url, expires_in_seconds, manifest } }. Default: 302 redirect to a 1-hour signed URL. The bucket has public-access-prevention enabled — the signed URL is the only reach.

Example

# Get the manifest + signed URL inline
curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/catalog/snapshot?format=json"

RECOMMENDATIONS

AI-assisted similarity and recommendation endpoints.

POST/api/v2/recommend

AI-assisted recommendations as canonical Film objects with per-pick reasons.

Parameters

Name	Type	Description
`prompt`req	string	Free-text description of what the user is in the mood for.
`limit`	number	Number of recommendations to return. Default 6.
`filters`	object	Optional pre-filters (genre, decade, min_rating, etc).

Response

Envelope { data: Array<{ film: Film, reason: string }> }. Reasons are short editorial strings explaining the match.

Example

curl -X POST -H "X-API-Key: hm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "rainy-night noir with a slow burn"}' \
  "https://hollywoodmetrics.ai/api/v2/recommend"

Authentication & Limits

KEYS, TIERS, ERRORS.

One header, four budgets, one error envelope.

KEYSX-API-Key

Generate a key from the dashboard. Keys start with hm_ and are scoped to your account's tier. Send them in the X-API-Key header on every request.

# All requests use the X-API-Key header.
curl -H "X-API-Key: hm_your_key" \
  "https://hollywoodmetrics.ai/api/v2/films/tt0068646"

Never embed a key in a browser bundle. Rotate the key from the dashboard if it leaks.

TIERSDaily budget

Tier	Price	Req / day
Free Site-only, read access on web.	$0	1
Writer Dev & sandbox, no production.	$9/mo	10
Producer Full v2 surface, prod-ready.	$99/mo	200
Studio AI endpoints, priority pool.	$999/mo	10,000

Budgets reset at 00:00 UTC. Exceeded budgets return 429 with a Retry-After hint.

ERRORSCanonical envelope

400Bad Request. Malformed parameter (e.g. min_rating=not-a-number).
401Unauthorized. Missing or invalid X-API-Key.
403Forbidden. Key exists but tier lacks access to this route.
404Not Found. No film matches the requested id.
429Rate Limited. Daily budget exhausted. Resets at 00:00 UTC.
503Unavailable. Catalog snapshot not yet generated; try again shortly.

# Errors return the same envelope, with an error block.
# Example: missing key on a paid route.
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key via X-API-Key header or ?key=...",
    "status": 401
  }
}

Checking your tier…

Ship something

ONE CALL.
EVERY FILM.

Mint a key, paste the curl, ship the integration. The v2 surface is GA and stable.

Start Building OpenAPI Spec

Open Dashboard•About the project•See the lenses

THE
INSTRUMENT.

Every film as a canonical record. Filter, sort, query, embed. A century of cinema, one REST surface, cursor-paginated and cacheable.

Films

74K+

1920–2026

Version

GA · stable

Latency

p95 < 200ms

edge-cached

Format

REST · JSON

cursor paging

{ "data": { "imdb_id": "tt0068646", "title": "The Godfather", "year": 1972, "runtime": 175, "genres": ["Crime", "Drama"], "director": "Francis Ford Coppola", "ratings": { "imdb": 9.2, "rt_critics": 97, "tmdb": 8.7, "master_score": 95.4 }, "poster": { "url": "https://...", "source": "gcs" }, "cast": [ /* top cast members */ ], "crew_summary": { /* directing, writing, camera, ... */ } } }

Name

Type

Description

q

string

Free-text search across title, overview, cast, crew, keywords.

genre

string

Comma-separated genres (AND match). Case-insensitive.

decade

string

e.g. 1990s or 1990.

year_min

number

Lower bound on release year.

year_max

number

Upper bound on release year.

min_rating

number

Minimum IMDb rating.

min_score

number

Minimum master score (composite).

min_votes

number

Minimum IMDb vote count.

director

string

Director name substring.

actor

string

Cast name substring.

language

string

ISO 639-1 code (e.g. en, fr, ja).

has_poster

boolean

true to return only films with a poster.

sort

string

field:dir, e.g. master_score:desc, year:asc.

fields

string

Comma-separated field projection.

limit

number

1–500, default 50.

cursor

string

Opaque pagination token from meta.next_cursor.

Name

Type

Description

idreq

string

IMDb id, e.g. tt0068646.

Name

Type

Description

has_poster

boolean

Filter to films with a poster.

fields

string

Comma-separated field projection (smaller lines).

Name

Type

Description

format

string

Pass format=json to get the manifest and signed URL inline. Default is a 302 redirect to the download.

Tier

Price

Req / day

Free

Site-only, read access on web.

Writer

Dev & sandbox, no production.

$9/mo

Producer

Full v2 surface, prod-ready.

$99/mo

200

Studio

AI endpoints, priority pool.

$999/mo

10,000

# Errors return the same envelope, with an error block. # Example: missing key on a paid route. HTTP/1.1 401 Unauthorized Content-Type: application/json { "error": { "code": "missing_api_key", "message": "Provide an API key via X-API-Key header or ?key=...", "status": 401 } }

THEINSTRUMENT.

THREE STEPS. ONE OBJECT.

RUN A REAL REQUEST.

EVERY ROUTE. EVERY PARAMETER.

FILMS

CATALOG

RECOMMENDATIONS

KEYS, TIERS, ERRORS.

ONE CALL.EVERY FILM.

THEINSTRUMENT.

THREE STEPS. ONE OBJECT.

RUN A REAL REQUEST.

EVERY ROUTE. EVERY PARAMETER.

FILMS

CATALOG

RECOMMENDATIONS

KEYS, TIERS, ERRORS.

ONE CALL.EVERY FILM.

THE
INSTRUMENT.

ONE CALL.
EVERY FILM.

THE
INSTRUMENT.

ONE CALL.
EVERY FILM.