---
title: "Top videos with creative breakdown"
method: POST
path: "/videos/creative"
tags: ["Videos"]
---

# Top videos with creative breakdown

`POST /videos/creative`

The shop's top videos ranked by GMV earned in the date range (defaults to the last 30 days, same ranking as /videos/performance), each enriched with the AI creative breakdown: hook, sell points, product niche, shot style, and videography. Use this to analyze WHY the top videos perform — not just how much they earned. Videos that haven't been analyzed yet keep their metrics and list the unavailable breakdown fields in creative.missing_fields; render those as 'not analyzed' rather than blank. Multi-shop requests (x-shop-id: all or comma-separated) mirror /videos/performance's semantics: one ranking across shops with a single top-level currency (USD fallback) — use a single shop when per-shop currency precision matters.

## Request body

- VideosCreativeRequest — POST /videos/creative request body.
  - `limit` integer
  - `sort_by` 'video_gmv' | 'views' | 'like_count' | 'order_count' | 'posted_date', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable

## Response `200`

Successful Response

- VideosCreativeResponse
  - `data` VideoCreativeItem[], required
    - `video_id` string, required
    - `title` string, nullable
    - `creator_handle` string, nullable
    - `tiktok_url` string, nullable — Canonical TikTok video permalink (the watch page): https://www.tiktok.com/@<handle>/video/<id>. Null when the handle is unavailable.
    - `video_gmv` number, nullable — GMV earned in the date range (not lifetime)
    - `views` integer, nullable — Views in the date range (not lifetime)
    - `like_count` integer, nullable
    - `comment_count` integer, nullable
    - `order_count` integer, nullable
    - `posted_date` string, nullable
    - `rank` integer, required
    - `creative` VideoCreativeBreakdown, required — AI creative analysis of the video (customers.video_analysis). Not every video has been analyzed — when ``analyzed`` is false, or when individual fields are null, ``missing_fields`` names the gaps so clients can render "not analyzed" instead of blanks.
      - `analyzed` boolean, required
      - `hook` VideoCreativeHook — Opening-seconds angle of the video.
        - `text` string, nullable — The hook line as spoken/shown
        - `classification` string, nullable — Hook type, e.g. problem-solution, curiosity
        - `reasoning` string, nullable — Why the analysis classified it this way
      - `sell_points` string[], nullable — Key selling points the video leans on
      - `product_niche` string, nullable — Product category leaf from the catalog, falling back to the content-angle tag
      - `shot_style` string[], nullable — How the video is framed and composed
      - `videography` VideoCreativeVideography — Camera work, setting, and presentation patterns.
        - `locations` string[], nullable
        - `lighting` string[], nullable
        - `product_showcase` string[], nullable
        - `notes` string, nullable — Free-text videography notes (older analyses store prose instead of structured fields)
      - `missing_fields` string[]
  - `currency` string, required
  - `date_range` DateRange
    - `start_date` string, nullable
    - `end_date` string, nullable
  - `coverage` VideosCreativeCoverage, required
    - `videos_returned` integer, required
    - `with_creative_analysis` integer, required
  - `total_count` integer, required — Total videos with performance data in the window (not just the top N)
  - `message` string, nullable — Set when there are no videos in the window (explicit empty state)
  - `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/5eefff009b5b/schema)