Competitors

The AI answers name brands in free text. A competitor is one of those brands that the workspace decided to track: Skoup then computes its share on the same answers as the brand’s own — retroactively, over the whole history, since every answer was already recorded. Tracking and untracking happen in the Skoup app; the API reads the tracked list with each competitor’s share on a market and a period.

The number of tracked competitors is capped by the plan. It counts distinct brands on all markets: tracking the same brand on France and the US takes one slot.

Statuses of a competitor

detectedtrackedremoved

detected brands are the ones the answers cite; only tracked ones are returned by the API. A removed competitor frees its slot and goes back to detected.

I want to…

I want to…	Call
Compare the brand with its tracked competitors	`GET /v1/brands/{brand}/competitors?market=FR&period=90d`
Know how many slots are left	The `Skoup-Quota-Competitors` header of that call
Be told when the list changes	`competitor.tracked`, `competitor.removed`
Spot a newcomer early	`alert.created` with `kind: "new_competitor"`
List the sites that cite competitors without the brand (PR, reviews, resellers)	`GET /v1/brands/{brand}/source-gaps?market=FR&period=90d`
Know when a source finally cites the brand	`task.verified` on a `source: "source_gap"` task

Scope: metrics:read.

Scenario: a weekly competitive digest


curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/competitors?market=FR&period=30d" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Run it after each weekly sampling.completed and post the ranking to your team’s channel.

Pitfalls

Read-only through the API. Tracking a competitor is a decision made in the app, where the quota and the upsell live.
A source to win is co-citation. source-gaps lists the sites cited in answers that name a competitor and not the brand; the site « belongs » to no competitor. The brand’s site and the competitors’ sites never appear. There is no « new source » event: read the list again after sampling.completed.
Shares are per market. A competitor may be tracked and never cited on a market: its share is then computed on answers that do not name it.