Samplings

A sampling is one measurement cycle of a brand on a market: every enabled query asked to every model chosen for the brand (among ChatGPT, Claude, Gemini, Perplexity, Grok, Mistral, DeepSeek and Qwen — Settings → Measured AI), several times each. Each answer is a run; Skoup reads in it the brands and products recommended, their position, and the prices and stock the model claims. All the metrics are computed from samplings.

Samplings run every Monday at 02:00 UTC (trigger: scheduled). Others are started at onboarding (onboarding), by hand in the app (manual), or to verify one alert on one query (targeted — the sampling then carries its query).

Statuses of a sampling

queuedrunningcompletedfailed

runs_total / runs_completed / runs_failed tell how far a running sampling is.

I want to…

I want to…	Call
List the samplings of a market	`GET /v1/brands/{brand}/samplings?market=FR`
List the ones that failed	`GET /v1/brands/{brand}/samplings?status=failed`
Read one sampling and its progress	`GET /v1/brands/{brand}/samplings/{sampling}`
Be told when one ends	`sampling.completed`, `sampling.failed`
Re-measure one query	Verify its alert: `POST …/alerts/{alert}/verify`

Scope: metrics:read.

Scenario: refresh your numbers after the weekly cycle


// POST handler of your webhook endpoint (signature verified first).
if (event.type === 'sampling.completed' && event.data.object.query === null) {
  await refreshDashboard(event.brand, event.data.object.market)
}

Pitfalls

The API does not start samplings. They are weekly, or started in the app; the only way to trigger one through the API is an alert verification, which re-samples a single query.
A targeted sampling is not “the latest measurement”. Filter sampling.completed on query === null to react to the weekly cycle only.
Test mode: samplings of the sandbox are frozen demo data; nothing runs.