---
title: "Per-session creator LIVE-attributed GMV rows"
method: POST
path: "/lives/list"
tags: ["Lives"]
---

# Per-session creator LIVE-attributed GMV rows

`POST /lives/list`

Paginated per-session view of creator LIVE-attributed GMV for one shop — one row per affiliate LIVE session with creator, timestamps, GMV, units, and engagement. 

Single-shop only. Defaults to the last 30 days ending today. Sort by ``live_gmv`` (default), ``start_time``, ``units_sold`` or ``views``. Empty ``sessions`` is a normal 200 response for shops without live-session data.

## Request body

- LivesListRequest — POST /lives/list request body. Per-session creator LIVE rows for one shop, paginated. Single shop only.
  - `start_date` string, date, nullable — Inclusive window start (YYYY-MM-DD). Defaults to 29 days before ``end_date``.
  - `end_date` string, date, nullable — Inclusive window end (YYYY-MM-DD). Defaults to today.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'live_gmv' | 'start_time' | 'units_sold' | 'views'
  - `sort_dir` 'asc' | 'desc'

## Response `200`

Successful Response

- LivesListResponse — Paginated per-session view of creator LIVE-attributed GMV for one shop.
  - `shop_id` integer, required
  - `currency_code` string, nullable — ISO currency code for the window; ``null`` when empty or mixed.
  - `start_date` string, required
  - `end_date` string, required
  - `page` integer, required
  - `page_size` integer, required
  - `total` integer, required — Total number of affiliate LIVE sessions matching the window.
  - `sessions` LivesSessionItem[], required — One entry per affiliate LIVE session on this page. Empty when the shop has no live-session data for the window (data-presence rollout — empty is a normal, non-error state).
    - `live_session_id` string, required
    - `title` string, nullable — LIVE session title.
    - `creator_handle` string, nullable — Creator username hosting the LIVE.
    - `start_time` string, nullable — ISO 8601 UTC start of the LIVE session.
    - `end_time` string, nullable — ISO 8601 UTC end of the LIVE session.
    - `duration_seconds` integer, nullable — LIVE session duration in seconds.
    - `live_gmv` number, nullable — Creator LIVE-attributed GMV (``affiliate_gmv``) for this session.
    - `units_sold` integer, nullable — Affiliate units sold in this session.
    - `views` integer, nullable
    - `likes` integer, nullable
    - `comments` integer, nullable
    - `ctr` number, nullable — Click-through rate as a decimal 0.0–1.0 (stored value, else product_clicks / product_impressions).
    - `engagement_rate` number, nullable — Engagement rate as a decimal 0.0–1.0+ (stored value, else (likes+comments+shares) / views).
    - `new_followers` integer, nullable
    - `avg_viewing_duration` integer, nullable — Average viewing duration in seconds for this session.

## 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/d4fe3e380424/schema)