---
title: "List videos"
method: POST
path: "/videos/list"
tags: ["Videos"]
---

# List videos

`POST /videos/list`

Affiliate videos and their performance metrics. Values represent lifetime totals per video (total views, total GMV, etc.). Data can be up to three days stale, given the delay in affiliate center.

## Request body

- VideosListRequest — POST /videos/list request body.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'video_gmv' | 'views' | 'units_sold' | 'posted_date' | 'like_count', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `creator_id` string, nullable
  - `creator_handle` string, nullable
  - `product_id` string, nullable
  - `product_ids` string[], nullable — Restrict to these product ids (IN filter). Max 50. The single product_id filter still works and is ANDed if both are supplied.
  - `min_gmv` number, nullable
  - `min_views` integer, nullable

## Response `200`

Successful Response

- VideosListPaginatedResponse
  - `data` VideoItem[], required
    - `video_id` string, required
    - `creator_id` string, nullable — Stable TikTok creator id for the video's author.
    - `title` string, nullable
    - `video_url` string, nullable — Thumbnail/preview image URL for the video (not the watch page).
    - `tiktok_url` string, nullable — Canonical TikTok video permalink (the watch page): https://www.tiktok.com/@<handle>/video/<id>.
    - `creator_handle` string, nullable
    - `product_id` string, nullable
    - `product_name` string, nullable
    - `views` integer, nullable
    - `like_count` integer, nullable
    - `comment_count` integer, nullable
    - `share_count` integer, nullable
    - `units_sold` integer, nullable
    - `video_gmv` number, nullable
    - `posted_date` string, nullable
  - `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

---

[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-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/578c830ce294/schema)