Competitors
List competitors
Read the brands AI answers name alongside yours, ranked by visibility over a window, with each one's share of voice.
/v1/brands/{brand_id}/competitorsBrands the answers name, ranked by visibility, as the Competitors page ranks them: the top limit, or with watched=true every watched rival. A rival is listed when named in more than one answer, named with its website, confirmed at its website by a tracking run, or watched.
Authorization
AuthorizationstringheaderrequiredYour API key as Bearer ranqo_sk_…. The account owner creates keys in Settings, under API keys. See Authentication.
Path parameters
brand_idstringrequiredThe brand id, from GET /v1/brands.
Query parameters
Every parameter is optional. A parameter the endpoint does not take is refused with unknown_parameter.
periodstring7d, 30d and 90d run from midnight in tz that many days back to now; 365d runs from midnight 365 days back to the end of today. Default 30d. Not with start_date.
Options:7d30d90d365d
start_datestringFirst day of a custom window, in tz. Send with end_date.
end_datestringLast day of a custom window, in tz, included. The window may span at most 366 days, both dates counted.
tzstringIANA time zone for day boundaries, such as Asia/Kolkata. Default UTC.
platformsstringEngines to count: claude, chatgpt, perplexity, gemini, grok, google_aio.
categoriesstringPrompt categories to count: discovery, problem_solution, use_case, expert, comparison, brand_research.
locationsstringPrompt locations to count, as stored on the prompt.
theme_idsstringTheme ids to count; none counts prompts with no theme.
is_brandedstringCount only prompts that do, or do not, name the brand.
Options:truefalse
limitintegerdefault: 25Rows to return, 1 to 100. Not applied with watched=true.
Range: 1 ≤ x ≤ 100
watchedstringtrue lists every watched rival, named or not.
Options:truefalse
curl "https://api.ranqo.ai/v1/brands/BRAND_ID/competitors" \
-H "Authorization: Bearer $RANQO_API_KEY"Sample data from an invented brand. Try it shows your own.
Response
The response body, as JSON.
brand_idstringwindowobjectThe answers a report counts: those from completed runs inside the window.
Show 6 fields insideHide the fields inside
startstringRFC 3339 timestamp in UTC.
endstringRFC 3339 timestamp in UTC.
previous_startstringThe comparison window runs from here to
start: the whole days beforestartfor7d,30dand90d, the same length as the window otherwise.time_zonestringperiodstring or nullThe preset, or null for a custom window. One of
7d,30d,90d,365d.carried_fromstring or nullRFC 3339 timestamp in UTC. Set when the window held no completed run: the figures are the latest run before it, which completed at this time, and nothing is compared.
answer_countintegerAnswers counted, after filters.
totalintegerBrands ranked, the brand included.
youobject or nullThe brand's own row, wherever it ranks; null when no answer matches.
Show 12 fields insideHide the fields inside
rankinteger or nullPlace by visibility, the brand included; null for a watched rival no answer named.
namestringdomainstring or nullNull when no domain could be confirmed; never guessed.
is_youbooleanis_watchedbooleanOn the brand's watchlist.
answer_countintegerAnswers naming it.
visibilityobjectPercent of answers naming it, 0-100, each engine weighted.
previousis null for a watched rival no answer in the window names.Show 3 fields insideHide the fields inside
currentnumber or nullNull when there is nothing to measure: no matching answer, or for position and sentiment no answer naming it, or for share of voice no mention of any brand.
previousnumber or nullOver the comparison window; null when that window has nothing to measure or the figures are carried.
changenumber or nullcurrentminusprevious, rounded once from the unrounded values as the dashboard shows it; null when either is null.
average_positionnumber or nullWhen named; lower is better.
sentiment_scorenumber or null0-100; null when never named.
share_of_voicenumber or nullIts share of the brand mentions the listed brands receive, 0-100.
movementstring or nullnew: absent from the comparison window and now at 5 points or more;rising: up by more than run-to-run noise. One ofnew,rising.platformsarray of objectsVisibility on each engine that answered.
Show 2 fields insideHide the fields inside
platformstringvisibilitynumber
dataarray of objectsEach item has the same fields as
you.
Response headers
X-Request-IdThe request id; quote it to support.
RateLimitRequests left in this window and seconds until it resets.
RateLimit-PolicyThe key's limit per window.
Errors
Errors are problem details (application/problem+json) with a stable code. See Errors for each one.