Visibility
Get visibility
Read a brand's visibility, share of voice, position and sentiment over a window, against the one before, by engine or category.
/v1/brands/{brand_id}/visibilityThe brand's visibility, position, sentiment and share of voice over a window, with the equal window before it, as the Visibility page shows them. Answers that failed are not counted.
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
group_bystringAdd a breakdown by engine or prompt category.
Options:platformcategory
curl "https://api.ranqo.ai/v1/brands/BRAND_ID/visibility" \
-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.
prompt_countintegerDistinct prompts behind them.
visibilityobjectPercent of answers naming the brand, 0-100, each engine weighted.
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_positionobjectAverage position when named, 1 = named first; lower is better. The same fields as
visibility.sentiment_scoreobject0-100: positive counts 1, neutral half, negative nothing. The same fields as
visibility.share_of_voiceobjectThe brand's share of brand mentions in the answers, 0-100. Rivals count when named in more than one answer, named with their website, confirmed at their website by a tracking run, or watched. The same fields as
visibility.position_distributionobjectAnswers by where the brand was named.
Show 5 fields insideHide the fields inside
firstintegersecondintegerthirdintegerfourth_plusintegernot_namedinteger
sentiment_distributionobjectAnswers naming the brand, by tone.
Show 3 fields insideHide the fields inside
positiveintegerneutralintegernegativeinteger
breakdownobject or nullPresent when
group_byis sent.Show 2 fields insideHide the fields inside
group_bystringOne of
platform,category.rowsarray of objectsShow 7 fields insideHide the fields inside
keystringThe engine id, or the prompt category (
uncategorizedfor none).answer_countintegernamed_countintegerAnswers that named the brand.
prompt_countintegerDistinct prompts behind those answers.
visibilitynumberPercent of these answers naming the brand, 0-100. A category row weights each engine, as the Visibility page does.
average_positionnumber or nullWhen named; lower is better. Null when never named.
sentiment_scorenumber or null0-100; null when never named.
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.