Datasets API endpoint
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).
/datasets/boxofficemojo/searchSearches theatrical box-office records from public Box Office Mojo charts and title pages — lifetime and yearly grosses, release groups, market breakdowns and franchise/brand/genre tags — stored in a search index.
Query parameters:
q: optional. Full-text query over title and taxonomy names. Max 256 characters.title_id: optional. Exact title id (IMDb tt… id used by Box Office Mojo). Max 32 characters.year: optional. Year that must appear in years_active (worldwide year chart presence).lifetime_year: optional. Primary lifetime chart year.gross_band: optional. Allowed values: under_50m, 50_100m, 100_250m, 250_500m, 500m_1b, over_1b.franchise: optional. Franchise name. Max 128 characters.brand: optional. Brand name. Max 128 characters.genre: optional. Genre name. Max 128 characters.in_lifetime_top_1000: optional boolean. Only titles in the lifetime worldwide top 1000 chart.hydrated: optional boolean. Only titles with hydrated release groups and market grosses.is_billion_dollar: optional boolean. Only titles with worldwide gross of at least $1B.min_worldwide / max_worldwide: optional. Lifetime worldwide gross bounds in whole USD dollars.min_domestic: optional. Minimum lifetime domestic gross in whole USD dollars.min_foreign_share: optional. Minimum foreign share of worldwide gross, 0 through 1.max_domestic_share: optional. Maximum domestic share of worldwide gross, 0 through 1.sort: optional. Allowed values: relevance, worldwide_desc, domestic_desc, peak_worldwide_desc, lifetime_rank_asc, year_desc, year_asc. Defaults to relevance with q, otherwise worldwide_desc.page: optional. 1-based page number. Default 1.page_size: optional. Default 20, max 100; page × page_size must not exceed 10000.1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.
| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| title_id | 1 | |
| title | 1 | |
| title_path | 1 | |
| title_url | 1 | boxofficemojo.com |
| lifetime_gross_worldwide | 1 | 2,799,439,100 |
| lifetime_gross_domestic | 1 | 858,373,000 |
| lifetime_rank_worldwide | 1 | 2 |
| lifetime_rank_domestic | 1 | 3 |
| lifetime_year | 1 | 2,019 |
| in_lifetime_top_1000_ww | 1 | true in 1 of 1 |
| in_lifetime_top_1000_dom | 1 | true in 1 of 1 |
| primary_release_group_id | 1 | |
| primary_release_group_name | 1 | |
| release_group_ids | 1 | |
| release_group_count | 1 | 2 |
| market_count | 1 | 57 |
| release_groups | 1 | median 2 entries |
| market_grosses | 1 | median 5 entries |
| domestic_share | 1 | 0.31 |
| foreign_share | 1 | 0.69 |
| gross_band | 1 | |
| is_billion_dollar | 1 | true in 1 of 1 |
| genre_ids | 1 | |
| genre_names | 1 | median 11 entries |
| years_active | 1 | median 2 entries |
| hydrated | 1 | true in 1 of 1 |
| sources | 1 | median 5 entries |
| first_seen_at | 1 | 2026-07-19 |
| last_crawled_at | 1 | 2026-10-05 |
| last_hydrated_at | 1 | 2026-07-21 |
| schema_version | 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text query over title and taxonomy names, max 256 characters | ||
| title_id | string | No | Exact title id (IMDb tt… id used by Box Office Mojo), max 32 characters | ||
| year | integer | No | Year that must appear in years_active | ||
| lifetime_year | integer | No | Primary lifetime chart year | ||
| gross_band | string | No | Gross band enum: under_50m, 50_100m, 100_250m, 250_500m, 500m_1b, over_1b Allowed values: under_50m, 50_100m, 100_250m, 250_500m, 500m_1b, over_1b. | ||
| franchise | string | No | Franchise name filter, max 128 characters | ||
| brand | string | No | Brand name filter, max 128 characters | ||
| genre | string | No | Genre name filter, max 128 characters | ||
| in_lifetime_top_1000 | boolean | No | Only titles in the lifetime worldwide top 1000 chart | ||
| hydrated | boolean | No | Only titles with hydrated release groups and market grosses | ||
| is_billion_dollar | boolean | No | Only titles with worldwide gross of at least $1B | ||
| min_worldwide | integer | No | Minimum lifetime worldwide gross in whole USD dollars | ||
| max_worldwide | integer | No | Maximum lifetime worldwide gross in whole USD dollars | ||
| min_domestic | integer | No | Minimum lifetime domestic gross in whole USD dollars | ||
| min_foreign_share | number | No | Minimum foreign share of worldwide gross, 0 through 1 | ||
| max_domestic_share | number | No | Maximum domestic share of worldwide gross, 0 through 1 | ||
| sort | string | No | Sort enum: relevance, worldwide_desc, domestic_desc, peak_worldwide_desc, lifetime_rank_asc, year_desc, year_asc Allowed values: relevance, worldwide_desc, domestic_desc, peak_worldwide_desc, lifetime_rank_asc, year_desc, year_asc. | ||
| page | integer | No | 1 | Page number, defaults to 1 | |
| page_size | integer | No | 20 and maxes at 100 | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/boxofficemojo/search?q=coffee&gross_band=under_50m&in_lifetime_top_1000=true&hydrated=true&is_billion_dollar=true&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "boxofficemojo",
"items": [
{
"title_id": "tt0499549",
"title": "Avatar",
"lifetime_gross_worldwide": 2923710708,
"gross_band": "over_1b",
"is_billion_dollar": true,
"hydrated": true
}
],
"page": 1,
"page_size": 20,
"total": 1000,
"sort": "worldwide_desc"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.boxOfficeMojoSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.BoxOfficeMojoSearchResponse | No | ||||
| data.dataset | string | No | ||||
| data.items | array | No | BoxOfficeMojoTitleRecord record, 57 fields: brand_ids, brand_names, domestic_share, first_seen_at, foreign_share, franchise_ids, franchise_names, genre_ids, genre_names, gross_band, hydrate_attempts, hydrate_failed and 28 more. Described under Box Office Mojo Dataset Item API. | |||
| data.page | integer | No | ||||
| data.page_size | integer | No | ||||
| data.sort | string | No | ||||
| data.total | integer | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/boxofficemojo/search?q=coffee&gross_band=under_50m&in_lifetime_top_1000=true&hydrated=true&is_billion_dollar=true&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"