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.

HTTP

GET https://api.ranqo.ai/v1/brands/{brand_id}/visibility

The 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.

Path parameters

Name	Type	Description
`brand_id`	string	The brand id, from `GET /v1/brands`.

Query parameters

Every parameter is optional. A parameter the endpoint does not take is refused with unknown_parameter.

Name	Type	Description
`period`	string	`7d`, `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`. One of `7d`, `30d`, `90d`, `365d`.
`start_date`	string	First day of a custom window, in `tz`. Send with `end_date`.
`end_date`	string	Last day of a custom window, in `tz`, included. The window may span at most 366 days, both dates counted.
`tz`	string	IANA time zone for day boundaries, such as `Asia/Kolkata`. Default `UTC`.
`platforms`	string	Engines to count: claude, chatgpt, perplexity, gemini, grok, google_aio.
`categories`	string	Prompt categories to count: discovery, problem_solution, use_case, expert, comparison, brand_research.
`locations`	string	Prompt locations to count, as stored on the prompt.
`theme_ids`	string	Theme ids to count; `none` counts prompts with no theme.
`is_branded`	string	Count only prompts that do, or do not, name the brand. One of `true`, `false`.
`group_by`	string	Add a breakdown by engine or prompt category. One of `platform`, `category`.

Response

The response body, as JSON.

Field	Type	Description
`brand_id`	string
`window`	object	The answers a report counts: those from completed runs inside the window.
`window.start`	string	RFC 3339 timestamp in UTC.
`window.end`	string	RFC 3339 timestamp in UTC.
`window.previous_start`	string	The comparison window runs from here to `start`: the whole days before `start` for `7d`, `30d` and `90d`, the same length as the window otherwise.
`window.time_zone`	string
`window.period`	string or null	The preset, or null for a custom window. One of `7d`, `30d`, `90d`, `365d`.
`window.carried_from`	string or null	RFC 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_count`	integer	Answers counted, after filters.
`prompt_count`	integer	Distinct prompts behind them.
`visibility`	object	Percent of answers naming the brand, 0-100, each engine weighted.
`visibility.current`	number or null	Null 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.
`visibility.previous`	number or null	Over the comparison window; null when that window has nothing to measure or the figures are carried.
`visibility.change`	number or null	`current` minus `previous`, rounded once from the unrounded values as the dashboard shows it; null when either is null.
`average_position`	object	Average position when named, 1 = named first; lower is better. The same fields as `visibility`.
`sentiment_score`	object	0-100: positive counts 1, neutral half, negative nothing. The same fields as `visibility`.
`share_of_voice`	object	The brand's share of brand mentions in the answers, 0-100. Rivals count when named in more than one answer, named with their website, or watched. The same fields as `visibility`.
`position_distribution`	object	Answers by where the brand was named.
`position_distribution.first`	integer
`position_distribution.second`	integer
`position_distribution.third`	integer
`position_distribution.fourth_plus`	integer
`position_distribution.not_named`	integer
`sentiment_distribution`	object	Answers naming the brand, by tone.
`sentiment_distribution.positive`	integer
`sentiment_distribution.neutral`	integer
`sentiment_distribution.negative`	integer
`breakdown`	object or null	Present when `group_by` is sent.
`breakdown.group_by`	string	One of `platform`, `category`.
`breakdown.rows`	array of objects
`breakdown.rows[].key`	string	The engine id, or the prompt category (`uncategorized` for none).
`breakdown.rows[].answer_count`	integer
`breakdown.rows[].named_count`	integer	Answers that named the brand.
`breakdown.rows[].prompt_count`	integer	Distinct prompts behind those answers.
`breakdown.rows[].visibility`	number	Percent of these answers naming the brand, 0-100. A category row weights each engine, as the Visibility page does.
`breakdown.rows[].average_position`	number or null	When named; lower is better. Null when never named.
`breakdown.rows[].sentiment_score`	number or null	0-100; null when never named.

Response headers

Header	Description
`X-Request-Id`	The request id; quote it to support.
`RateLimit`	Requests left in this window and seconds until it resets.
`RateLimit-Policy`	The key's limit per window.

Example request

curl

curl "https://api.ranqo.ai/v1/brands/BRAND_ID/visibility" \
  -H "Authorization: Bearer $RANQO_API_KEY"

Errors

Errors are problem details (application/problem+json) with a stable code. See Errors for each one.

Status	Codes
400	`invalid_parameter`, `unknown_parameter`, `api_key_in_url`
401	`missing_api_key`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `api_key_orphaned`
403	`plan_upgrade_required`, `subscription_inactive`
404	`not_found`
429	`rate_limited`
500	`internal_error`
503	`service_unavailable`

Name

Type

Description

brand_id

string

The brand id, from GET /v1/brands.

Query parameters

Every parameter is optional. A parameter the endpoint does not take is refused with unknown_parameter.

Name	Type	Description
`period`	string	`7d`, `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`. One of `7d`, `30d`, `90d`, `365d`.
`start_date`	string	First day of a custom window, in `tz`. Send with `end_date`.
`end_date`	string	Last day of a custom window, in `tz`, included. The window may span at most 366 days, both dates counted.
`tz`	string	IANA time zone for day boundaries, such as `Asia/Kolkata`. Default `UTC`.
`platforms`	string	Engines to count: claude, chatgpt, perplexity, gemini, grok, google_aio.
`categories`	string	Prompt categories to count: discovery, problem_solution, use_case, expert, comparison, brand_research.
`locations`	string	Prompt locations to count, as stored on the prompt.
`theme_ids`	string	Theme ids to count; `none` counts prompts with no theme.
`is_branded`	string	Count only prompts that do, or do not, name the brand. One of `true`, `false`.
`group_by`	string	Add a breakdown by engine or prompt category. One of `platform`, `category`.

Response

The response body, as JSON.

Field	Type	Description
`brand_id`	string
`window`	object	The answers a report counts: those from completed runs inside the window.
`window.start`	string	RFC 3339 timestamp in UTC.
`window.end`	string	RFC 3339 timestamp in UTC.
`window.previous_start`	string	The comparison window runs from here to `start`: the whole days before `start` for `7d`, `30d` and `90d`, the same length as the window otherwise.
`window.time_zone`	string
`window.period`	string or null	The preset, or null for a custom window. One of `7d`, `30d`, `90d`, `365d`.
`window.carried_from`	string or null	RFC 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_count`	integer	Answers counted, after filters.
`prompt_count`	integer	Distinct prompts behind them.
`visibility`	object	Percent of answers naming the brand, 0-100, each engine weighted.
`visibility.current`	number or null	Null 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.
`visibility.previous`	number or null	Over the comparison window; null when that window has nothing to measure or the figures are carried.
`visibility.change`	number or null	`current` minus `previous`, rounded once from the unrounded values as the dashboard shows it; null when either is null.
`average_position`	object	Average position when named, 1 = named first; lower is better. The same fields as `visibility`.
`sentiment_score`	object	0-100: positive counts 1, neutral half, negative nothing. The same fields as `visibility`.
`share_of_voice`	object	The brand's share of brand mentions in the answers, 0-100. Rivals count when named in more than one answer, named with their website, or watched. The same fields as `visibility`.
`position_distribution`	object	Answers by where the brand was named.
`position_distribution.first`	integer
`position_distribution.second`	integer
`position_distribution.third`	integer
`position_distribution.fourth_plus`	integer
`position_distribution.not_named`	integer
`sentiment_distribution`	object	Answers naming the brand, by tone.
`sentiment_distribution.positive`	integer
`sentiment_distribution.neutral`	integer
`sentiment_distribution.negative`	integer
`breakdown`	object or null	Present when `group_by` is sent.
`breakdown.group_by`	string	One of `platform`, `category`.
`breakdown.rows`	array of objects
`breakdown.rows[].key`	string	The engine id, or the prompt category (`uncategorized` for none).
`breakdown.rows[].answer_count`	integer
`breakdown.rows[].named_count`	integer	Answers that named the brand.
`breakdown.rows[].prompt_count`	integer	Distinct prompts behind those answers.
`breakdown.rows[].visibility`	number	Percent of these answers naming the brand, 0-100. A category row weights each engine, as the Visibility page does.
`breakdown.rows[].average_position`	number or null	When named; lower is better. Null when never named.
`breakdown.rows[].sentiment_score`	number or null	0-100; null when never named.