Competitors

Events associés : competitor.removed · competitor.tracked

Endpoints

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

L’objet Competitor

Attributs

idstring
Identifiant unique de l'objet (préfixé, opaque).
objectstring
competitor
namestring
keystring
Normalized identity of the brand in the answers (stable across spellings).
domainstringnullable
marketstring
Code du marché (pays ISO, par ex. 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
Valeurs possibles : detected · declared
trackedboolean
tracked_atstring
removed_atstringnullable
visibilityobject
livemodeboolean
true pour les données réelles, false pour le bac à sable du mode test.
createdinteger
Time at which the object was created (unix timestamp, seconds).

L'objet Competitor


{
  "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
}

L’objet Source gap

Attributs

objectstring
source_gap
hoststring
The site, without www.. @example bikeradar.com
categoryenum
Valeurs possibles : 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 pour les données réelles, false pour le bac à sable du mode test.

L'objet Source gap


{
  "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.

Paramètres

brandstringobligatoire
Brand id (br_…).
limitinteger
Nombre d'objets à renvoyer, entre 1 et 100 (20 par défaut).
starting_afterstring
Curseur : l'id du dernier objet de la page précédente.

Retour

Un dictionnaire dont la propriété data contient jusqu’à limit objets competitor, du plus récent au plus ancien, et has_more indique s’il reste une page. Lève une erreur en cas de problème.

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()

Réponse


{
  "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.