Pages

Endpoints

GET/v1/brands/{brand}/insights
GET/v1/brands/{brand}/pages

The Page signal object

Attributes

objectstring
page_signal
pathstring
The normalised path, the key every source is joined on. @example /velo-gravel
urlstring
googleobjectnullable
Google Search Console, 28 days; ctr is a ratio (0–1), prev_* the 28 days before. null = Search Console not connected.
Show child attributes
- clicksinteger
- impressionsinteger
- ctrnumber
- positionnumbernullable
- prev_clicksintegernullable
- prev_impressionsintegernullable
- prev_positionnumbernullable
trafficobjectnullable
Visits measured by the Skoup script, 28 days. null = script not installed.
Show child attributes
- visitsinteger
- engaged_visitsinteger
- ai_visitsinteger
- transactionsinteger
- ai_transactionsinteger
analyticsobjectnullable
Google Analytics landing-page sessions, every channel summed, 28 days ending 3 days ago. null = GA4 not connected or not synced yet.
Show child attributes
- sessionsinteger
- organic_sessionsinteger
- conversionsinteger
- revenuenumber
ai_ordersobjectnullable
Orders attributed to an AI assistant that landed on the page, 28 days. null = no order data on the market.
Show child attributes
- ordersinteger
- revenuenumber
- currencystringnullable
citationsintegernullable
AI answers citing the page, every model summed. null = no sampling in the window.
citations_by_modelarray of object
The same citations per model; models that never cite the page are absent.
Show child attributes
- modelstring
- citationsinteger
issuesobjectnullable
Problems of the latest crawl; empty keys = crawled without problem. null = no crawl yet.
Show child attributes
- keysarray of string
- severityenumnullable
  Possible values: error · warning
livemodeboolean
true for live data, false for the test-mode sandbox.

The Page signal object


{
  "object": "page_signal",
  "path": "string",
  "url": "https://nordvelo.com/velo-gravel",
  "google": {
    "clicks": 12,
    "impressions": 12,
    "ctr": 27.5,
    "position": 27.5,
    "prev_clicks": 12,
    "prev_impressions": 12,
    "prev_position": 27.5
  },
  "traffic": {
    "visits": 12,
    "engaged_visits": 12,
    "ai_visits": 12,
    "transactions": 12,
    "ai_transactions": 12
  },
  "analytics": {
    "sessions": 12,
    "organic_sessions": 12,
    "conversions": 12,
    "revenue": 27.5
  },
  "ai_orders": {
    "orders": 12,
    "revenue": 27.5,
    "currency": "EUR"
  },
  "citations": 12,
  "citations_by_model": [
    {
      "model": "string",
      "citations": 12
    }
  ],
  "issues": {
    "keys": [
      "string"
    ],
    "severity": "error"
  },
  "livemode": true
}

The Insight object

Attributes

objectstring
insight
keystring
Stable while the finding holds. @example low_ctr:3f2a9c…
kindenum
Possible values: ranked_not_cited · cited_no_visits · low_ctr · declining · traffic_with_issues · ai_converts_less · tracking_gap
pathstring
urlstring
factsobject
The measured numbers of the rule; the keys depend on kind, rates and CTR are ratios (0–1).
Show child attributes
- positionnumbernullable
- impressionsinteger
- clicksintegernullable
- citationsinteger
- visitsintegernullable
- ctrnumber
- expected_ctrnumber
- estimated_clicksinteger
- prev_clicksinteger
- prev_positionnumbernullable
- issuesarray of string
- ai_visitsinteger
- ai_ratenumber
- other_ratenumber
- analytics_sessionsinteger
has_open_taskboolean
A Skoup task opened from this finding is still open.
livemodeboolean
true for live data, false for the test-mode sandbox.

The Insight object


{
  "object": "insight",
  "key": "string",
  "kind": "ranked_not_cited",
  "path": "/velo-gravel",
  "url": "https://hooks.example.com/skoup",
  "facts": {
    "position": 27.5,
    "impressions": 12,
    "clicks": 12,
    "citations": 12,
    "visits": 12,
    "ctr": 27.5,
    "expected_ctr": 27.5,
    "estimated_clicks": 12,
    "prev_clicks": 12,
    "prev_position": 27.5,
    "issues": [
      "string"
    ],
    "ai_visits": 12,
    "ai_rate": 27.5,
    "other_rate": 27.5,
    "analytics_sessions": 12
  },
  "has_open_task": true,
  "livemode": true
}

List insights

GET/v1/brands/{brand}/insights

The deterministic findings read from the page signals, every model included: a page ranked on Google that no assistant cites, a cited page without AI visits, a low CTR, a decline, traffic on a page in error, AI visits that convert less, a tracking gap. A finding whose source is missing is never reported. Highest stake first.

Parameters

brandstringrequired
Brand id (br_…).
limitinteger
Number of objects to return, between 1 and 100 (default 20).
starting_afterstring
Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit insight objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/insights?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/insights?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/insights?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/insights?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/insights",
  "has_more": false,
  "data": [
    {
      "object": "insight",
      "key": "string",
      "kind": "ranked_not_cited",
      "path": "/velo-gravel",
      "url": "https://hooks.example.com/skoup",
      "facts": {
        "position": 27.5,
        "impressions": 12,
        "clicks": 12,
        "citations": 12,
        "visits": 12,
        "ctr": 27.5,
        "expected_ctr": 27.5,
        "estimated_clicks": 12,
        "prev_clicks": 12,
        "prev_position": 27.5,
        "issues": [
          "string"
        ],
        "ai_visits": 12,
        "ai_rate": 27.5,
        "other_rate": 27.5,
        "analytics_sessions": 12
      },
      "has_open_task": true,
      "livemode": true
    }
  ]
}

List page signals

GET/v1/brands/{brand}/pages

One row per page of the brand’s site with what every source measured over the last 28 days: Google Search Console, the Skoup script, Google Analytics, the AI citations, the AI-attributed orders and the crawl. A null block was not measured (source not connected): never read it as 0. Up to 500 pages, busiest first.