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

# Ranking Report

`POST /svm/reports/ranking`

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", "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).

## 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 title, such as IMDB and LFTV IDs
        - `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
    - `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.net/luminatedata/apis/authentication.md) · [All operations](https://skmtc.net/luminatedata/apis/authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/luminatedata/authentication/revisions/81d2bd1553e1/schema)