Pages et constats

Un signal de page est une page du site de la marque avec ce que chaque source a mesuré : Google Search Console, le script Skoup, Google Analytics, les citations des IA, les commandes attribuées aux IA et le dernier crawl. Un constat est ce que Skoup en déduit par des règles fixes, sans modèle d’IA : les mêmes chiffres donnent toujours les mêmes constats.

Rien n’est stocké : les deux listes sont calculées à l’appel, par marché, tous modèles d’IA confondus.

Je veux…

Je veux…	Appel
Lire toutes les pages avec leurs signaux (BI, tableur)	`GET /v1/brands/{brand}/pages?market=FR`
Lister ce qui mérite l’attention, le plus gros enjeu d’abord	`GET /v1/brands/{brand}/insights?market=FR`
Savoir si un constat est déjà traité	`has_open_task` sur le constat
Suivre la correction d’un constat	`task.verified` sur une tâche `source: "insight"`

Scope : metrics:read.

Ce que veut dire chaque constat

`kind`	Sens	`facts`
`ranked_not_cited`	La page est bien classée sur Google et aucun assistant ne la cite.	`position`, `impressions`, `clicks`
`cited_no_visits`	Des assistants citent la page et le script n’y a vu aucune visite IA.	`citations`, `visits`
`low_ctr`	Le CTR est nettement sous ce que sa position devrait rapporter.	`position`, `impressions`, `ctr`, `expected_ctr`, `estimated_clicks`
`declining`	Les clics ont chuté par rapport aux 28 jours précédents.	`clicks`, `prev_clicks`, `position`, `prev_position`
`traffic_with_issues`	La page reçoit du trafic et le crawl y a relevé une erreur bloquante.	`clicks`, `visits`, `issues`
`ai_converts_less`	Les visites IA convertissent à moins de la moitié du taux des autres visites.	`ai_visits`, `ai_rate`, `other_rate`
`tracking_gap`	Le script Skoup voit moins de la moitié des sessions rapportées par Google Analytics.	`visits`, `analytics_sessions`

Scénario : la liste hebdomadaire des pages à corriger


curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/insights?market=FR" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Lancez-le après chaque sampling.completed hebdomadaire et gardez les constats dont has_open_task vaut false.

Pièges

null n’est pas 0. Un bloc null (google, traffic, analytics, ai_orders, issues) ou un citations à null signifie que la source n’est pas connectée ou n’a jamais été mesurée. Une fois la source connectée, une page qui n’y figure pas porte des zéros. Un constat dont la source manque n’est jamais rendu : une liste vide ne prouve pas que tout va bien.
Une fenêtre de 28 jours. Search Console et Google Analytics couvrent 28 jours finissant il y a 3 jours, le script et les commandes les 28 derniers jours ; prev_* = les 28 jours d’avant. Les citations viennent des samplings des 30 derniers jours.
La clé est le chemin. Les sources sont jointes sur le chemin normalisé (sans hôte, sans query string, sans slash final) : deux hôtes qui servent /guide font une seule ligne. La key d’un constat vaut {kind}:{sha1 du chemin}, stable tant que le constat tient ; pas d’id ni d’event, relisez la liste.
Les taux sont des ratios. ctr, expected_ctr, ai_rate et other_rate vont de 0 à 1.
Les revenus ne sont pas convertis. analytics.revenue est dans la devise de la propriété GA4, ai_orders.revenue dans ai_orders.currency.
500 pages au plus, les plus fréquentées d’abord (clics + visites).