Metrics

The metrics of a brand are the numbers of its Skoup home screen, on one market and one period: its visibility in AI answers (share of shelf, with a 95 % confidence interval, the weekly change and the average position), the accuracy of what the assistants say about its prices and stock, its readiness score and its perception score. They are read with the same code as the screens: an API value never contradicts the app.

Measurements come from the weekly samplings, every Monday at 02:00 UTC. A period (30d, 90d — the default — or 12m) is the window of samplings the numbers are computed on.

I want to…

I want to…	Call
Read a brand’s numbers on its primary market	`GET /v1/brands/{brand}/metrics`
Read them on another market, over a year	`GET /v1/brands/{brand}/metrics?market=US&period=12m`
See how the AI perceive one product	`GET /v1/brands/{brand}/products/{product}/perception`
Know when new numbers are available	Listen to `sampling.completed`

Scope: metrics:read.

Scenario: a Looker dashboard refreshed every Monday

Listen to sampling.completed. When a full weekly sampling lands (data.object.query is null — a targeted re-sampling carries its query), pull the metrics and the attribution of that market and write them to your warehouse.


curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/metrics?market=FR&period=90d" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
 
curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/attribution?market=FR&period=90d" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Pitfalls

null is not zero. A block is null when nothing was measured yet (no sampling on the market, no audit, no perception judged). A share of 0 is a real measurement: the brand was never cited.
Compare like with like. A 30-day and a 12-month share are computed on different windows; store the period with the number.
Perception follows ignored gaps. When the team ignores a gap in Skoup (a false positive of the judge), its verdicts leave the perception score, in the app and in the API alike; the score can move without a new sampling.
An unknown market answers 422 parameter_invalid with param: "market".