Requêtes

Une requête est une question qu’un acheteur pourrait poser à un assistant IA — « meilleur vélo gravel carbone à moins de 3 000 € ». À chaque sampling hebdo, Skoup pose chaque requête activée d’un marché à chaque modèle, plusieurs fois, puis lit quelles marques et quels produits les réponses recommandent. Le panel de requêtes est ce sur quoi la visibilité de la marque est mesurée.

Une requête appartient à un marché et est écrite dans la langue de ce marché ; il n’existe pas de requête parente traduite par marché. Seules les requêtes activées sont posées, et elles comptent dans le quota de requêtes de l’espace.

Statuts d’une requête

enableddisabled

Désactiver une requête libère une place du quota et arrête sa mesure dès le prochain sampling ; son historique est conservé. La réactiver reprend une place.

Je veux…

Je veux…	Appel
Lister les requêtes d’un marché, avec leur visibilité	`GET /v1/brands/{brand}/queries?market=FR`
Lister seulement les requêtes activées	`GET /v1/brands/{brand}/queries?enabled=true`
Lire une requête	`GET /v1/brands/{brand}/queries/{query}`
Ajouter une requête au panel	`POST /v1/brands/{brand}/queries` (`text`, `market`, `category`)
Arrêter de mesurer une requête	`PATCH /v1/brands/{brand}/queries/{query}` avec `enabled: false`
Savoir combien de places il reste	L’en-tête `Skoup-Quota-Queries` de tout appel sur les requêtes

Scopes : queries:read, queries:write. Events : aucun en propre — les nouvelles mesures arrivent avec sampling.completed.

Scénario : pousser les questions entendues par votre support


curl -X POST https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/queries \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Idempotency-Key: support-faq-2026-09-23-12" \
  -H "Content-Type: application/json" \
  -d '{"text":"vélo gravel léger pour bikepacking","market":"FR","category":"Gravel"}'

La réponse porte Skoup-Quota-Queries: limit=150, remaining=37. La requête est mesurée à partir du prochain sampling hebdo.

Pièges

Le quota compte les requêtes activées, tous marchés confondus. Quand il est atteint, créer ou activer une requête répond 422 quota_exceeded ; désactivez-en une autre d’abord.
Le marché doit être activé sur la marque, sinon l’appel répond 422 parameter_invalid sur market.
Une nouvelle requête n’a pas encore de visibilité : son bloc visibility reste vide tant qu’aucun sampling ne l’a posée.