---
title: "Ranking Report"
method: POST
path: "/svm/reports/ranking"
tags: ["Reports"]
---

# Ranking Report

`POST /svm/reports/ranking`

## Request

- Base URL: `https://api.luminatedata.com`
- URL: `https://api.luminatedata.com/svm/reports/ranking`
- Auth: API key in header `x-api-key` and API key in header `authorization`

Retrieves a list of most-watched titles within custom parameters.

## Request body

- RankingRequest: Ranking report request body
  - `depth` integer, required: The number of titles to return
  - `video_type` 'tv_show' | 'movie', required: Type of video content, either ‘movie' or 'tv_show'
  - `start_date` string, date, required: First date used in the aggregation of the consumption data. Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).
  - `end_date` string, date, required: Last date used in the aggregation of the consumption data. Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).
  - `genres` string[], nullable: Optional list of genres to filter results by. If not provided, all genres are included. Valid values: "action & adventure", "animation", "comedy", "crime", "documentary", "drama", "family", "fantasy", "horror", "kids", "musical", "mystery", "romance", "science fiction", "thriller", "western".
  - `platforms` string[]: Filter results by one or more platforms. If not provided, all platforms are included. Valid values: "AMC+", "Apple TV", "BritBox", "Discovery+", "Disney+", "HBO Max", "Hulu", "Netflix", "Paramount+", "Peacock", "Prime Video", "Tubi".
  - `ranked_by` 'minutes_watched' | 'views': Metric to rank results by. Default is 'minutes_watched', alternative is 'views'.
  - `tv_show_granularity` 'series' | 'season', nullable: Optional field to distinguish between TV shows and series. 'season' is default.
  - `source` string[], nullable: Optional list to filter results by content source. If not provided, both original and non-original content are included. Valid values: "original", "non-original".
  - `release_information` ReleaseInformation, nullable: Optional release date range filter. If provided, results are filtered to titles released within the specified date range (inclusive).
    - `release_date_min` string, date: Minimum release date filter (inclusive). Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).
    - `release_date_max` string, date: Maximum release date filter (inclusive). Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).
  - `country_of_origin` string[], nullable: Optional list of countries of origin to filter results by, as case-insensitive ISO 3166-1 alpha-2 codes. If not provided, all countries are included. Titles with any of the given countries of origin are returned. Only supported for movie and tv_show season reports; rejected when tv_show_granularity is series.
  - `original_language` string[], nullable: Optional list of original languages to filter results by, as two-letter ISO 639-1 language codes (e.g., ['en', 'fr']); matching is case-insensitive. Languages without a two-letter code use a three-letter ISO 639-2/639-3 code (e.g., 'yue' for Cantonese, 'zxx' for no dialogue). If not provided, all languages are included. Titles with any of the given original languages are returned. Only supported for movie and tv_show season reports; rejected when tv_show_granularity is series.

## Response `200`

Successfully retrieved ranking data

- SuccessfulResponseRankingResponse
  - `data` RankingResponse
    - `video_type` string: Video Type of movie or tv_show
    - `depth` integer: Depth of values to be returned between 1 and 200
    - `start_date` string, date: Start date of the report period
    - `end_date` string, date: End date of the report period
    - `genres` string[]: Genre filters applied to results
    - `items` RankingItem[]: List of ranking results
      - `report_rank` integer: Position in the ranking
      - `title_id` string: Unique Luminate ID assigned to the item
      - `title` string: Title of the item
      - `season` string: ID of the TV show’s season, only provided for ranking reports with video_type is tv_show
      - `genres` string[]: Genres associated with the item
      - `metrics` RankingMetrics: Consumption data for the item
        - `minutes_watched` integer: Total minutes watched
        - `views` integer: Total number of views
        - `duration_to_date` integer: Runtime to date in minutes
        - `data_status` string: Data status indicator (official or preliminary)
      - `platform_availability` string[]: Platforms this title is available on
      - `external_ids` ExternalIds: External identifiers for the talent, such as the IMDb name ID
        - `imdb` string[]: IMDB ID
        - `lftv` string[]: Luminate Film & TV project ID
      - `original` boolean: Indicates whether the title is an original production for a platform
      - `original_platform` string: The platform for which this is an original production. Null if the title is not an original.
    - `platforms` string[]: Platform filters applied to results
    - `country_of_origin` string[]: Country of origin filters applied to results
    - `original_language` string[]: Original language filters applied to results, as lowercase two-letter ISO 639-1 language codes (e.g., ['en', 'fr']). Languages without a two-letter code use a three-letter ISO 639-2/639-3 code (e.g., 'yue' for Cantonese, 'zxx' for no dialogue).
    - `tv_show_granularity` string: Field to distinguish between a season or a series level TV Show.
    - `release_information` ReleaseInformation, nullable: Optional release date range filter. If provided, results are filtered to titles released within the specified date range (inclusive).
      - `release_date_min` string, date: Minimum release date filter (inclusive). Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).
      - `release_date_max` string, date: Maximum release date filter (inclusive). Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).

## Other responses

- `400`: Invalid request parameters

---

[API](https://skmtc.dev/luminatedata/apis/luminate-svm-api.md) - [All operations](https://skmtc.dev/luminatedata/apis/luminate-svm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/luminatedata/apis/luminate-svm-api/revisions/ff683b83f008?raw)