---
title: "LIVE metric cards with trend"
method: POST
path: "/lives/metrics"
tags: ["Lives"]
---

# LIVE metric cards with trend

`POST /lives/metrics`

The five LIVE performance cards the portal shows above the session table — Live GMV, Live Units Sold, Live Count, Avg Engagement Rate and Avg Viewing Duration. Each card carries its ``value``, ``unit``, the percent ``change`` against the immediately preceding window of equal length, and ``chart_data``: one point per day of the window, zero-filled on days with no sessions so the series length always matches the range. 

**Differs from POST /lives/summary** — that returns flat window totals. This returns the same totals plus period-over-period change and a daily series, and accepts the portal's ``filters`` / ``search`` so the cards can be scoped to a creator or a GMV band. Engagement rate is a decimal (0.0-1.0), durations are seconds. 

Single-shop only; defaults to the last 30 days ending today. LIVE analytics is region-gated — shops outside the supported regions get a 403 ``REGION_NOT_SUPPORTED``. A shop with no sessions returns zeroed cards as a normal 200.

## Request body

- LivesMetricCardsRequest — Body for POST /lives/metrics — ``shop_id`` comes from ``x-shop-id``.
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `filters` LivesFilters — Maps to the frontend filter sliders (ACU/PCU dropped — no data source).
    - `gmv` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `views` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `duration` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `unitsSold` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `likes` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `comments` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `ctr` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
    - `engagementRate` RangeFilter
      - `min` number, nullable
      - `max` number, nullable
  - `search` string, nullable

## Response `200`

Successful Response

- LivesMetricsResponse
  - `success` boolean
  - `metrics` MetricCard[], required
    - `label` string, required
    - `value` number, required
    - `unit` string, required
    - `change` number, required
    - `comparison_text` string, required
    - `tooltip_text` string, required
    - `chart_data` number[]

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