Competitors

Related events: competitor.removed · competitor.tracked

Endpoints

GET/v1/brands/{brand}/competitors
GET/v1/brands/{brand}/source-gaps

The Competitor object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
competitor
namestring
keystring
Normalized identity of the brand in the answers (stable across spellings).
domainstringnullable
marketstring
Market code (ISO country, e.g. FR).
originenum
How a competitor entered the referential. - detected → suggested by the sampling (it was already cited in answers) - declared → typed by a user, by brand name or domain
Possible values: detected · declared
trackedboolean
tracked_atstring
removed_atstringnullable
visibilityobject
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Competitor object


{
  "id": "comp_031DIivuBKog78mwjgnch7",
  "object": "competitor",
  "name": "Canyon",
  "key": "canyon",
  "domain": "canyon.com",
  "market": "FR",
  "origin": "detected",
  "tracked": false,
  "tracked_at": "2026-09-22T10:04:11Z",
  "removed_at": "2026-09-23T08:30:00Z",
  "livemode": true,
  "created": 1790071451
}

The Source gap object

Attributes

objectstring
source_gap
hoststring
The site, without www.. @example bikeradar.com
categoryenum
Possible values: reseller · forum · video · media
answers_without_brandnumber
Answers citing the site that name a competitor and not the brand, over the period.
answers_with_brandnumber
Answers citing the site that name the brand, over the period.
queriesstring
Distinct queries behind answers_without_brand.
competitorsarray of string
The competitor brands named most often alongside the site.
pagesarray of string
Up to three pages of the site the answers cite.
last_cited_atstring
ISO-8601 UTC.
has_open_taskstring
livemodeboolean
true for live data, false for the test-mode sandbox.

The Source gap object


{
  "object": "source_gap",
  "host": "string",
  "category": "reseller",
  "answers_without_brand": 27.5,
  "answers_with_brand": 27.5,
  "queries": "string",
  "competitors": [
    "string"
  ],
  "pages": [
    "string"
  ],
  "last_cited_at": "2026-09-21T02:40:00Z",
  "has_open_task": "string",
  "livemode": true
}

List tracked competitors

GET/v1/brands/{brand}/competitors

The competitor brands tracked on a market, with the share of the market’s AI answers citing each over the period — the figures of the Competitors screen, every model included.

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 competitor 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/competitors?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/competitors?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/competitors?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/competitors?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/competitors",
  "has_more": false,
  "data": [
    {
      "id": "comp_031DIivuBKog78mwjgnch7",
      "object": "competitor",
      "name": "Canyon",
      "key": "canyon",
      "domain": "canyon.com",
      "market": "FR",
      "origin": "detected",
      "tracked": false,
      "tracked_at": "2026-09-22T10:04:11Z",
      "removed_at": "2026-09-23T08:30:00Z",
      "livemode": true,
      "created": 1790071451
    }
  ]
}

List sources to win

GET/v1/brands/{brand}/source-gaps

The third-party sites (media, forums, resellers, videos) the AI assistants cite in answers that name a competitor and not the brand — the pages where a mention, a review or a listing would put the brand in the answers. Most cited without the brand first, every model included.