# List brands

> List the brands an API key can read, oldest first, each with the stored scores of its latest completed tracking run.

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

```http
GET https://api.ranqo.ai/v1/brands
```

The brands this key reads, oldest first. A key restricted to some brands lists only those.

## Query parameters

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

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | integer | `50` | Items per page, 1 to 100. |
| `cursor` | string |  | The `next_cursor` of the previous page. |

## Response

The response body, as JSON.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of objects |  |
| `data[].id` | string |  |
| `data[].name` | string |  |
| `data[].slug` | string | The brand's path segment in the dashboard. |
| `data[].domain` | string |  |
| `data[].domain_aliases` | array of strings | Other domains the brand owns. |
| `data[].category` | string or null |  |
| `data[].description` | string or null |  |
| `data[].location` | string or null | The market the brand targets, as entered. |
| `data[].reach` | string or null | One of `worldwide`, `country`, `local`. |
| `data[].language` | string or null | ISO 639-1 code; null means English. |
| `data[].platforms` | array of strings | The engines tracked for this brand. |
| `data[].is_tracking_paused` | boolean |  |
| `data[].created_at` | string | RFC 3339 timestamp in UTC. |
| `data[].latest_run` | object or null | Scores stored on the run itself when it completed. The latest completed run; null before the first. |
| `data[].latest_run.id` | string |  |
| `data[].latest_run.completed_at` | string | RFC 3339 timestamp in UTC. |
| `data[].latest_run.platforms` | array of strings | The engines the run asked. |
| `data[].latest_run.visibility` | number or null | The run's own stored visibility, 0-100, one decimal. |
| `data[].latest_run.average_position` | number or null | The average position when named, one decimal; null when never named. |
| `has_more` | boolean | Whether another page follows. |
| `next_cursor` | string or null | Pass as `cursor` for the next page; null on the last page. |

## 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" \
  -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), [`invalid_cursor`](https://ranqo.ai/docs/api/errors#invalid_cursor), [`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) |
| 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) |