---
title: "Time-series metrics"
method: POST
path: "/metrics/timeseries"
tags: ["Metrics"]
---

# Time-series metrics

`POST /metrics/timeseries`

Fetch time-series data for one or more metrics over a date range. Returns daily/weekly/monthly data points for charting trends. Available metrics: gmv (affiliate-attributed), total_gmv (full shop from the Seller Center scrape), live_gmv (creator LIVE-attributed, from live_sessions — see POST /lives/* for the per-shop currency-aware view), sc_affiliate_live_gmv (creator LIVE GMV as Seller Center itself reports it, under By order source → Creator → Lives — order-date attributed, so it does not match live_gmv; use it to reconcile against a Seller Center export), creators, videos_posted, video_views, gmv_per_video, gmv_per_sample, creators_reached, creators_messaged, tc_invites_sent, samples_approved, sample_requests, gmv_driving_videos, new_creators_posting, open_collabs, accepted_tc_count, emails_sent, dm_responses, reply_rate. Seller Center whole-shop cards: orders, units_sold, aov, ctr, conversion_rate (aov/ctr/conversion_rate are ratios computed over the full window, not averages of daily ratios; 0 for shops not yet on the Seller Center sync). Granularity (day/week/month) is auto-detected based on the date range if not specified. IMPORTANT: 'creators' returns distinct creators PER DAY — summing daily values double-counts creators active on multiple days. For the headline distinct count over the full period, use POST /metrics/summary instead. Similarly, gmv_per_video and gmv_per_sample are daily ratios — use /metrics/summary for the period-level headline values. Dates default to the newest day with settled data for the shop (typically yesterday; up to 2 days back while a day finalizes).

## Request body

- TimeseriesRequest — POST /metrics/timeseries request body.
  - `metrics` string[], required
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `granularity` 'day' | 'week' | 'month', nullable

## Response `200`

Successful Response

- TimeseriesResponse
  - `data` object, required
  - `granularity` string, required
  - `start_date` string, required
  - `end_date` string, required
  - `currency` string, required
  - `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)