Getting Started with the Luminate SV(M) API
Access streaming TV show and movie metadata and consumption metrics
🔐 Authenticate
The first step to accessing the Luminate SV(M) API is to go through the authentication process. Please review the Authentication documentation for an outline of the steps and requirements.
🔎 Find Titles in Our Catalog Using Search
The /search endpoint enables users to find content based on a title name or external ID.
- Search by title name: Perform a search based on title name by providing a
queryterm in the request body. Titles are returned in the response based on text similarity. For titles that originate outside of the United States, SV(M) titles typically refer to the English/US title. For TV Shows, titles are returned as seasons, meaning each season of a show will appear in the response. - Search by External ID: Look for exact IDs from catalogs external to SV(M) by providing an
identifier. The search accepts either Luminate Film and TV project ID or IMDB ID. Responses will be returned at a series level for TV shows. In most cases, the user should expect 1 title returned.
Users can search by title name or ID, but not both - providing both a query and identifier in a request will result in a 400 error.
Optional from and size parameters can be used for pagination for searches that yield many results.
{
"data": {
"hits": [
{
"id": "91b4ec3ad5a4b7a7eeb44d91befb3d1d",
"release_information": [
{
"release_date": "2025-01-17"
}
],
"creators": [
"Dan Erickson"
],
"video_type": "tv_show",
"season": "2",
"title": "Severance"
},
{
"id": "91b4ec3ad5a4b7a7eeb44d91befb3d1d",
"release_information": [
{
"release_date": "2022-02-18"
}
],
"creators": [
"Dan Erickson"
],
"video_type": "tv_show",
"season": "1",
"title": "Severance"
}
],
"from": 0,
"size": 2,
"total_hits": 2
}
}📑 Use batch search to find many titles at once
Using the /search/batch endpoint, users can search for up to 50 titles in SV(M) using a single query. Each line of JSON will accept the the same parameters as a single search. The response will contain a JSON object with a list of all the searches attempted.
Example Request
{"identifier": "tt13443470"}
{"identifier": "tt31868189"}
{"identifier": "tt11280740"}{
"data": {
"responses": [
{
"hits": [
{
"id": "512180cd6cb60422d79ad36e4b4863ac",
"release_information": [
{
"release_date": "2022-11-22"
}
],
"creators": [
"Alfred Gough",
"Miles Millar"
],
"video_type": "tv_show",
"external_ids": {
"imdb": [
"tt13443470"
],
"lftv": [
"187998"
]
},
"title": "Wednesday"
}
],
"query": null,
"identifier": "tt13443470",
"from": 0,
"size": 10,
"total_hits": 1,
"success": true,
"error_message": null
},
{
"hits": [
{
"id": "840fbdde72e6960716e16793c5d3b64c",
"release_information": [
{
"release_date": "2025-07-25"
}
],
"creators": [
"Kyle Newacheck"
],
"video_type": "movie",
"external_ids": {
"imdb": [
"tt31868189"
],
"lftv": [
"226049"
]
},
"title": "Happy Gilmore 2"
}
],
"query": null,
"identifier": "tt31868189",
"from": 0,
"size": 10,
"total_hits": 1,
"success": true,
"error_message": null
},
{
"hits": [
{
"id": "91b4ec3ad5a4b7a7eeb44d91befb3d1d",
"release_information": [
{
"release_date": "2022-02-18"
}
],
"creators": [
"Dan Erickson"
],
"video_type": "tv_show",
"external_ids": {
"imdb": [
"tt11280740"
],
"lftv": [
"173951"
]
},
"title": "Severance"
}
],
"query": null,
"identifier": "tt11280740",
"from": 0,
"size": 10,
"total_hits": 1,
"success": true,
"error_message": null
}
]
}
}📈 Discover Popular Streaming Content
Retrieve a list of the most popular content in a time period using the /reports/ranking endpoint.
- identify the type of content you are looking for (TV or Movie) using the
video_typeparameter - change the
depthof the report, anywhere from 1 to 200 titles - limit the report to specific genres or available platforms
In the response, external IDs (Luminate Film and TV, IMDb) are provided to enable users to easily match content to other catalogs.
{
"data": {
"video_type": "tv_show",
"depth": 2,
"start_date": "2025-01-01",
"end_date": "2025-02-01",
"items": [
{
"report_rank": 1,
"title_id": "2741515c8560aa9486adb61d8d4742ed",
"title": "Landman",
"season": "1",
"genres": [
"drama",
"western"
],
"metrics": {
"minutes_watched": 8971871144,
"views": 16492410,
"duration_to_date": 544
},
"external_ids": {
"imdb": [
"tt14186672"
],
"lftv": [
"188318"
]
}
},
{
"report_rank": 2,
"title_id": "f038e05ada2c490585455fdd7e41cca3",
"title": "The Night Agent",
"season": "2",
"genres": [
"action & adventure",
"drama",
"thriller"
],
"metrics": {
"minutes_watched": 4393419497,
"views": 8564171,
"duration_to_date": 513
},
"external_ids": {
"imdb": [
"tt13918776"
],
"lftv": [
"192924"
]
}
}
]
}
}📊 Get Access to Data
Use IDs to retrieve data via the movie and TV show endpoints. For TV shows, the ID refers to the series entity, but endpoints are provided to drilldown to a season or episode as needed.
- Movies
/movies
- TV Shows
/tv_shows(Series)/tv_shows/{id}/seasons(Season)/tv_shows/{id}/seasons/{season}/episodes(Episode)
Metadata and metrics endpoints in the Luminate SV(M) API are separate.
- Metadata endpoints provide information such as title name, release date, genres, and external IDs to help identify and describe content.
- Metrics endpoints are available for each of the aforementioned entities and provide the below consumption metrics for the requested time frame.
- Minutes watched
- Views
- Demographic breakouts - only via the Movies and TV Show Season metrics endpoints, when available.
- Age
- Gender
- For more information about the SV(M) model and metrics, please visit the SV(M) Knowledge Base .
{
"data": {
"id": "60f1a2907e3178c7994ebc48fe54b9b7",
"title": "The Pitt",
"overview": "The daily lives of healthcare professionals in a Pittsburgh hospital as they juggle personal crises, workplace politics, and the emotional toll of treating critically ill patients, revealing the resilience required in their noble calling.",
"release_information": [
{
"release_date": "2025-01-09"
}
],
"genres": [
"drama"
],
"platform_availability": [
"HBO Max"
],
"studios": [
"John Wells Productions",
"Max",
"R. Scott Gemmill Productions",
"Sky Studios",
"Warner Bros. Television",
"R. Scott Gemmill Productions, Inc."
],
"creators": [
"R. Scott Gemmill"
],
"season": "1",
"episodes": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14",
"15"
],
"duration": 727,
"external_ids": {
"imdb": [
"tt31938062"
],
"lftv": [
"225712"
]
}
}
}{
"data": {
"id": "60f1a2907e3178c7994ebc48fe54b9b7",
"season": "1",
"start_date": "2025-01-10",
"end_date": "2025-01-12",
"metrics": [
{
"name": "minutes_watched",
"granularity": "daily",
"value": [
{
"date": "2025-01-10",
"value": 56392132
},
{
"date": "2025-01-11",
"value": 115247766
},
{
"date": "2025-01-12",
"value": 98147530
}
]
},
{
"name": "views",
"granularity": "daily",
"value": [
{
"date": "2025-01-10",
"value": 542232,
"duration_to_date": 104
},
{
"date": "2025-01-11",
"value": 1108151,
"duration_to_date": 104
},
{
"date": "2025-01-12",
"value": 943726,
"duration_to_date": 104
}
]
}
],
"demographics": [
{
"name": "gender",
"confidence": "high",
"value": [
{
"value": "Female",
"percentage_of_total": 56
},
{
"value": "Male",
"percentage_of_total": 44
}
]
},
{
"name": "age",
"confidence": "high",
"value": [
{
"value": "18-24",
"percentage_of_total": 9
},
{
"value": "25-34",
"percentage_of_total": 16
},
{
"value": "35-44",
"percentage_of_total": 16
},
{
"value": "45-54",
"percentage_of_total": 18
},
{
"value": "55-64",
"percentage_of_total": 15
},
{
"value": "65-74",
"percentage_of_total": 15
},
{
"value": "75+",
"percentage_of_total": 11
}
]
}
]
}
}📬 Improve Your Queries with Developer-Friendly Error Messaging
Encountered a 4xx or 5xx error when querying the Luminate SV(M) API? No fear! Our developer-friendly error messages will quickly identify the root cause and guide you to a successful request.
{
"error": {
"message": "Bad Request. Please refer to validation_failures for details.",
"code": 400,
"validation_failures": [
{
"field": "video_type",
"issue": "tv is not a supported value. Supported values are TV_SHOW and MOVIE"
}
]
}
}🛟 We're here to help!
The SV(M) Knowledge Base has more information about SV(M) methodology, such as how the model works, how demographic data is calculated, and more.
If you have other questions about how to use the API, please reach out to [email protected].
Updated 13 days ago