---
title: "List videos with retention / hook-quality metrics"
method: GET
path: "/videos/retention"
tags: ["Videos"]
---

# List videos with retention / hook-quality metrics

`GET /videos/retention`

## Request

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

Your shop's videos with per-video **completion rate** (`watch_finish_rate`), exposure (`impressions`), views, CTR and engagement — the organic hook-quality signal.

TikTok exposes a 2-second view rate only for GMV Max ad creatives (`video_view_rate_2s` on `/campaigns/{id}/creative-metrics`); for organic videos the retention metric is completion, so use `watch_finish_rate` as the quality bar (`min_watch_finish_rate` filters to it). Ordered strongest-hook first.

Scope: videos in the shop's own Seller Center analytics (posted for the shop).

## Query parameters

- `creator_handle` string, nullable: Restrict to a creator by (partial) TikTok handle.
- `min_watch_finish_rate` number, nullable: Only videos whose completion rate is at least this (percent).
- `min_views` integer, nullable: Only videos with at least this many views. Pair with `min_watch_finish_rate` to use completion rate as a quality bar — without a floor a 1-view video reads as 100% completion and tops the ranking.
- `page` integer: Page number (1-indexed).
- `page_size` integer: Rows per page (max 100).

## Response `200`

Successful Response

- VideoRetentionResponse
  - `data` VideoRetention[], required
    - `video_id` string, required
    - `video_url` string, nullable
    - `video_name` string, nullable
    - `video_duration_s` number, nullable: Video length in seconds.
    - `publish_time` string, nullable
    - `creator_handle` string, nullable
    - `creator_alias` string, nullable
    - `views` integer, nullable
    - `impressions` integer, nullable: Video exposure count (impressions).
    - `clicks` integer, nullable
    - `ctr_rate` number, nullable: Click-through rate, percent.
    - `watch_finish_rate` number, nullable: Video-completion rate, percent — the share of viewers who watched to the end. The organic hook-quality signal (TikTok exposes no 2-second view rate for organic videos, only completion).
    - `likes` integer, nullable
    - `comments` integer, nullable
    - `shares` integer, nullable
    - `new_followers` integer, nullable
    - `gpm` number, nullable: Gross revenue per mille.
    - `revenue` number, nullable
    - `currency` string, nullable
    - `products` VideoProduct[], nullable
      - `product_id` string, nullable
      - `id` string, nullable: Deprecated alias of `product_id`; use `product_id`.
      - `name` string, nullable
  - `pagination` PublicApiCorePaginationPaginationMeta, required: Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 1 breaking, 2 info
  - the `data/items/publish_time/anyOf[subschema #1]/` response's property format changed from `date-time` to no format for status `200`
  - added the optional property `data/items/products/anyOf[subschema #1]/items/product_id` to the response with the `200` status
  - response property `data/items/products/anyOf[subschema #1]/items/id` deprecated
- **2026-09-10** `7dad11366a32`: 1 info
  - endpoint added

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