---
title: "Search the Box Office Mojo dataset"
method: GET
path: "/datasets/boxofficemojo/search"
tags: ["Datasets"]
---

# Search the Box Office Mojo dataset

`GET /datasets/boxofficemojo/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/boxofficemojo/search`
- Auth: API key in header `x-api-key`

Searches theatrical box-office records from Box Office Mojo charts and title pages. Filter by title id, year, franchise/brand/genre, gross band, lifetime top-1000 membership, hydration status, and worldwide/domestic gross ranges. Sort enum: `relevance`, `worldwide_desc`, `domestic_desc`, `peak_worldwide_desc`, `lifetime_rank_asc`, `year_desc`, `year_asc`. gross_band enum: `under_50m`, `50_100m`, `100_250m`, `250_500m`, `500m_1b`, `over_1b`. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).

## Query parameters

- `q` string
- `title_id` string
- `year` integer
- `lifetime_year` integer
- `gross_band` 'under_50m' | '50_100m' | '100_250m' | '250_500m' | '500m_1b' | 'over_1b'
- `franchise` string
- `brand` string
- `genre` string
- `in_lifetime_top_1000` boolean
- `hydrated` boolean
- `is_billion_dollar` boolean
- `min_worldwide` integer
- `max_worldwide` integer
- `min_domestic` integer
- `min_foreign_share` number
- `max_domestic_share` number
- `sort` 'relevance' | 'worldwide_desc' | 'domestic_desc' | 'peak_worldwide_desc' | 'lifetime_rank_asc' | 'year_desc' | 'year_asc'
- `page` integer
- `page_size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsBoxOfficeMojoSearchResponseDoc
  - `code` integer
  - `data` DatasetsBoxOfficeMojoSearchResponse
    - `dataset` string
    - `items` EsBoxOfficeMojoTitleRecord[]
      - `brand_ids` string[]
      - `brand_names` string[]
      - `domestic_share` number
      - `first_seen_at` string
      - `foreign_share` number
      - `franchise_ids` string[]
      - `franchise_names` string[]
      - `genre_ids` string[]
      - `genre_names` string[]
      - `gross_band` string
      - `hydrate_attempts` integer
      - `hydrate_failed` boolean
      - `hydrated` boolean
      - `in_lifetime_top_1000_dom` boolean
      - `in_lifetime_top_1000_ww` boolean
      - `is_billion_dollar` boolean
      - `last_crawled_at` string
      - `last_hydrated_at` string
      - `lifetime_gross_domestic` integer
      - `lifetime_gross_worldwide` integer
      - `lifetime_rank_domestic` integer
      - `lifetime_rank_worldwide` integer
      - `lifetime_year` integer
      - `market_count` integer
      - `market_grosses` object[]: MarketGrosses keeps the hydrated region/market tables as opaque objects so the mapping stays flexible; the public query surface can expand later.
      - `peak_worldwide_gross` integer
      - `peak_worldwide_year` integer
      - `primary_release_group_id` string
      - `primary_release_group_name` string
      - `release_group_count` integer
      - `release_group_ids` string[]
      - `release_groups` EsBoxOfficeMojoReleaseGroup[]
        - `domestic` integer
        - `international` integer
        - `markets` string
        - `name` string
        - `path` string
        - `rollout` string
        - `url` string
        - `worldwide` integer
      - `schema_version` integer
      - `sources` string[]
      - `title` string
      - `title_id` string
      - `title_path` string
      - `title_url` string
      - `year_grosses` EsBoxOfficeMojoYearGross[]
        - `domestic` integer
        - `domestic_share` number
        - `foreign` integer
        - `foreign_share` number
        - `rank_worldwide` integer
        - `release_group_id` string
        - `release_group_name` string
        - `worldwide` integer
        - `year` integer
      - `years_active` integer[]
    - `page` integer
    - `page_size` integer
    - `sort` string
    - `total` integer
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)