Competitors

List competitors

Read the brands AI answers name alongside yours, ranked by visibility over a window, with each one's share of voice.

HTTP

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

Brands 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, or watched.

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	Default	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`.
`limit`	integer	`25`	Rows to return, 1 to 100. Not applied with `watched=true`.
`watched`	string		`true` lists every watched rival, named or not. One of `true`, `false`.

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.
`total`	integer	Brands ranked, the brand included.
`you`	object or null	The brand's own row, wherever it ranks; null when no answer matches.
`you.rank`	integer or null	Place by visibility, the brand included; null for a watched rival no answer named.
`you.name`	string
`you.domain`	string or null	Null when no domain could be confirmed; never guessed.
`you.is_you`	boolean
`you.is_watched`	boolean	On the brand's watchlist.
`you.answer_count`	integer	Answers naming it.
`you.visibility`	object	Percent of answers naming it, 0-100, each engine weighted. `previous` is null for a watched rival no answer in the window names.
`you.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.
`you.visibility.previous`	number or null	Over the comparison window; null when that window has nothing to measure or the figures are carried.
`you.visibility.change`	number or null	`current` minus `previous`, rounded once from the unrounded values as the dashboard shows it; null when either is null.
`you.average_position`	number or null	When named; lower is better.
`you.sentiment_score`	number or null	0-100; null when never named.
`you.share_of_voice`	number or null	Its share of the brand mentions the listed brands receive, 0-100.
`you.movement`	string or null	`new`: absent from the comparison window and now at 5 points or more; `rising`: up by more than run-to-run noise. One of `new`, `rising`.
`you.platforms`	array of objects	Visibility on each engine that answered.
`you.platforms[].platform`	string
`you.platforms[].visibility`	number
`data`	array of objects	Each item has the same fields as `you`.

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/competitors" \
  -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	Default	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`.
`limit`	integer	`25`	Rows to return, 1 to 100. Not applied with `watched=true`.
`watched`	string		`true` lists every watched rival, named or not. One of `true`, `false`.

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.
`total`	integer	Brands ranked, the brand included.
`you`	object or null	The brand's own row, wherever it ranks; null when no answer matches.
`you.rank`	integer or null	Place by visibility, the brand included; null for a watched rival no answer named.
`you.name`	string
`you.domain`	string or null	Null when no domain could be confirmed; never guessed.
`you.is_you`	boolean
`you.is_watched`	boolean	On the brand's watchlist.
`you.answer_count`	integer	Answers naming it.
`you.visibility`	object	Percent of answers naming it, 0-100, each engine weighted. `previous` is null for a watched rival no answer in the window names.
`you.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.
`you.visibility.previous`	number or null	Over the comparison window; null when that window has nothing to measure or the figures are carried.
`you.visibility.change`	number or null	`current` minus `previous`, rounded once from the unrounded values as the dashboard shows it; null when either is null.
`you.average_position`	number or null	When named; lower is better.
`you.sentiment_score`	number or null	0-100; null when never named.
`you.share_of_voice`	number or null	Its share of the brand mentions the listed brands receive, 0-100.
`you.movement`	string or null	`new`: absent from the comparison window and now at 5 points or more; `rising`: up by more than run-to-run noise. One of `new`, `rising`.
`you.platforms`	array of objects	Visibility on each engine that answered.
`you.platforms[].platform`	string
`you.platforms[].visibility`	number
`data`	array of objects	Each item has the same fields as `you`.