# List competitors

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

Source: https://ranqo.ai/docs/api/reference/list-competitors

```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

```bash title="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](https://ranqo.ai/docs/api/errors) for each one.

| Status | Codes |
| --- | --- |
| 400 | [`invalid_parameter`](https://ranqo.ai/docs/api/errors#invalid_parameter), [`unknown_parameter`](https://ranqo.ai/docs/api/errors#unknown_parameter), [`api_key_in_url`](https://ranqo.ai/docs/api/errors#api_key_in_url) |
| 401 | [`missing_api_key`](https://ranqo.ai/docs/api/errors#missing_api_key), [`invalid_api_key`](https://ranqo.ai/docs/api/errors#invalid_api_key), [`api_key_revoked`](https://ranqo.ai/docs/api/errors#api_key_revoked), [`api_key_expired`](https://ranqo.ai/docs/api/errors#api_key_expired), [`api_key_orphaned`](https://ranqo.ai/docs/api/errors#api_key_orphaned) |
| 403 | [`plan_upgrade_required`](https://ranqo.ai/docs/api/errors#plan_upgrade_required), [`subscription_inactive`](https://ranqo.ai/docs/api/errors#subscription_inactive) |
| 404 | [`not_found`](https://ranqo.ai/docs/api/errors#not_found) |
| 429 | [`rate_limited`](https://ranqo.ai/docs/api/errors#rate_limited) |
| 500 | [`internal_error`](https://ranqo.ai/docs/api/errors#internal_error) |
| 503 | [`service_unavailable`](https://ranqo.ai/docs/api/errors#service_unavailable) |