---
title: "Top videos on a given date"
method: GET
path: "/halo/viral-videos"
tags: ["Halo Effect Tracker"]
---

# Top videos on a given date

`GET /halo/viral-videos`

## Request

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

The shop's TikTok videos posted on one date, ranked by views — the drill-down for a spike. When the timeseries shows Amazon revenue jumping on the 14th and the analysis says the best lag is 3 days, this answers what went up on the 11th that caused it. Each video carries views, GMV, units sold and engagement counts, plus Reacher CDN links (permanent thumbnail, mirrored video) for the videos we have mirrored — null for the rest. 

``date`` filters on posting date, not activity date, so a video that kept accruing views is ranked by its lifetime views under the day it was posted. Single-shop only.

## Query parameters

- `date` string, date, required: The posting date to rank (YYYY-MM-DD).
- `limit` integer: Max videos to return.

## Response `200`

Successful Response

- HaloViralVideosResponse
  - `shop_id` integer, required
  - `date` string, required
  - `videos` HaloViralVideo[], required
    - `video_id` string, nullable
    - `title` string, nullable
    - `video_url` string, nullable
    - `thumbnail` string, nullable
    - `views` integer, nullable
    - `units_sold` integer, nullable
    - `video_gmv` number, nullable
    - `like_count` integer, nullable
    - `comment_count` integer, nullable
    - `share_count` integer, nullable
    - `creator_name` string, nullable
    - `posted_date` string, nullable

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

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

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/halo/viral-videos/get.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)