---
title: "Creator video leaderboard"
method: POST
path: "/videos/leaderboard"
tags: ["Videos"]
---

# Creator video leaderboard

`POST /videos/leaderboard`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/videos/leaderboard`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

Creator-level shoppable-video leaderboard for a campaign window. Aggregates attributed video GMV and units per creator over a posted-date range (optionally restricted to specific product_ids), each with a per-product breakdown, ranked by total video GMV (default). Use this instead of paginating /videos/list + joining by hand: one row per creator with total_video_gmv, total_units_sold, qualifying_video_count (DISTINCT videos), and a products[] breakdown. min_gmv is a per-video-row threshold consistent with /videos/list. Multi-shop requests (x-shop-id: all or comma-separated) aggregate creators across shops, but only when every shop shares one currency — GMV cannot be summed across currencies, so a mixed-currency shop set is rejected (400); scope x-shop-id to a single currency/region.

## Request body

- VideoLeaderboardRequest: POST /videos/leaderboard request body. Creator-level shoppable-video leaderboard for a campaign window: aggregate each creator's attributed video GMV/units over a posted-date range, optionally restricted to specific products, with a per-product breakdown.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'total_video_gmv' | 'total_units_sold' | 'qualifying_video_count', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `product_ids` string[], nullable
  - `min_gmv` number, nullable

## Response `200`

Successful Response

- VideoLeaderboardResponse
  - `data` LeaderboardCreatorItem[], required
    - `creator_id` string, nullable
    - `creator_handle` string, nullable
    - `total_video_gmv` number, nullable
    - `total_units_sold` integer, nullable
    - `qualifying_video_count` integer: DISTINCT video_id count for this creator across the selected products — a video spanning several selected products counts once.
    - `products` LeaderboardProductBreakdown[]
      - `product_id` string, nullable
      - `product_name` string, nullable
      - `video_gmv` number, nullable
      - `units_sold` integer, nullable
      - `video_count` integer
  - `currency` string, required
  - `pagination` unknown, required
  - `date_range` DateRange
    - `start_date` string, nullable
    - `end_date` string, nullable
  - `shops_queried` string[], nullable: Shop names included when querying multiple shops (x-shop-id: all or comma-separated).

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 1 info
  - api operation id `videos_leaderboard_videos_leaderboard_post` removed and replaced with `videos_leaderboard`

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/videos/leaderboard/post.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)