Pages & insights

A page signal is one page of the brand’s site with what every source measured about it: Google Search Console, the Skoup script, Google Analytics, the AI citations, the AI-attributed orders and the latest crawl. An insight is a finding Skoup derives from those signals with fixed rules, no model involved: the same numbers always give the same findings.

Nothing is stored: both lists are computed when you call them, per market, every AI model included.

I want to…

I want to…	Call
Read every page with its signals (BI, spreadsheet)	`GET /v1/brands/{brand}/pages?market=FR`
List what deserves attention, highest stake first	`GET /v1/brands/{brand}/insights?market=FR`
Know whether a finding is already handled	`has_open_task` on the insight
Follow the fix of a finding	`task.verified` on a `source: "insight"` task

Scope: metrics:read.

What each insight means

`kind`	Meaning	`facts`
`ranked_not_cited`	The page ranks well on Google and no assistant cites it.	`position`, `impressions`, `clicks`
`cited_no_visits`	Assistants cite the page and the script saw no AI visit on it.	`citations`, `visits`
`low_ctr`	The CTR is well under what its position should earn.	`position`, `impressions`, `ctr`, `expected_ctr`, `estimated_clicks`
`declining`	Clicks dropped against the previous 28 days.	`clicks`, `prev_clicks`, `position`, `prev_position`
`traffic_with_issues`	The page receives traffic and the crawl found a blocking error.	`clicks`, `visits`, `issues`
`ai_converts_less`	AI visits convert at under half the rate of the other visits.	`ai_visits`, `ai_rate`, `other_rate`
`tracking_gap`	The Skoup script sees under half the sessions Google Analytics reports.	`visits`, `analytics_sessions`

Scenario: a weekly list of pages to fix


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

Run it after each weekly sampling.completed and keep the insights whose has_open_task is false.

Pitfalls

null is not 0. A null block (google, traffic, analytics, ai_orders, issues) or a null citations means the source is not connected or was never measured. Once a source is connected, a page absent from it carries zeros. An insight whose source is missing is never reported: an empty list does not prove everything is fine.
One 28-day window. Search Console and Google Analytics cover 28 days ending 3 days ago, the script and the orders the last 28 days; prev_* is the 28 days before. Citations come from the samplings of the last 30 days.
The key is the path. Sources are joined on the normalised path (no host, no query string, no trailing slash): two hosts serving /guide are one row. An insight’s key is {kind}:{sha1 of the path}, stable while the finding holds; there is no id and no event, read the list again.
Rates are ratios. ctr, expected_ctr, ai_rate and other_rate go from 0 to 1.
Revenue is not converted. analytics.revenue is in the currency of the GA4 property, ai_orders.revenue in ai_orders.currency.
Up to 500 pages, busiest first (clicks + visits).