Samplings

Un sampling est un cycle de mesure d’une marque sur un marché : chaque requête activée posée à chaque modèle choisi pour la marque (parmi ChatGPT, Claude, Gemini, Perplexity, Grok, Mistral, DeepSeek et Qwen — Réglages → IA mesurées), plusieurs fois. Chaque réponse est un run ; Skoup y lit les marques et produits recommandés, leur position, et les prix et stocks affirmés par le modèle. Toutes les mesures sont calculées à partir des samplings.

Les samplings tournent chaque lundi à 02:00 UTC (trigger: scheduled). D’autres sont lancés à l’onboarding (onboarding), à la main dans l’app (manual), ou pour vérifier une alerte sur une requête (targeted — le sampling porte alors sa query).

Statuts d’un sampling

queuedrunningcompletedfailed

runs_total / runs_completed / runs_failed indiquent l'avancement d'un sampling en cours.

Je veux…

Je veux…	Appel
Lister les samplings d’un marché	`GET /v1/brands/{brand}/samplings?market=FR`
Lister ceux qui ont échoué	`GET /v1/brands/{brand}/samplings?status=failed`
Lire un sampling et son avancement	`GET /v1/brands/{brand}/samplings/{sampling}`
Être prévenu de la fin	`sampling.completed`, `sampling.failed`
Re-mesurer une requête	Vérifier son alerte : `POST …/alerts/{alert}/verify`

Scope : metrics:read.

Scénario : rafraîchir vos chiffres après le cycle hebdo


// Handler POST de votre endpoint webhook (signature vérifiée d'abord).
if (event.type === 'sampling.completed' && event.data.object.query === null) {
  await refreshDashboard(event.brand, event.data.object.market)
}

Pièges

L’API ne lance pas de samplings. Ils sont hebdomadaires ou lancés dans l’app ; le seul moyen d’en déclencher un par l’API est une vérification d’alerte, qui re-sample une seule requête.
Un sampling ciblé n’est pas « la dernière mesure ». Filtrez sampling.completed sur query === null pour ne réagir qu’au cycle hebdo.
Mode test : les samplings du bac à sable sont des données de démo figées ; rien ne tourne.