# List outreach targets

> List a brand's Outreach targets in the board's rank order: the subreddits, threads and pages AI answers cite.

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

```http
GET https://api.ranqo.ai/v1/brands/{brand_id}/outreach-targets
```

The brand's Outreach targets, ranked by opportunity score as the board ranks them. A board refresh re-scores them, so a cursor from before a refresh is refused: start again.

## 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 |
| --- | --- | --- | --- |
| `limit` | integer | `50` | Items per page, 1 to 100. |
| `cursor` | string |  | The `next_cursor` of the previous page. |
| `channel` | string |  | One of `reddit`, `publication`. |
| `play` | string |  | One of `comment`, `post`, `pitch`. |
| `status` | string |  | One of `suggested`, `in_progress`, `done`, `dismissed`. |

## Response

The response body, as JSON.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of objects |  |
| `data[].id` | string |  |
| `data[].channel` | string | One of `reddit`, `publication`. |
| `data[].kind` | string | A subreddit, one of its threads, or a published page. One of `community`, `thread`, `page`. |
| `data[].play` | string | `comment` in a thread AI cites, `post` in a community, `pitch` a publication. One of `comment`, `post`, `pitch`. |
| `data[].url` | string |  |
| `data[].domain` | string |  |
| `data[].subreddit` | string or null |  |
| `data[].title` | string or null |  |
| `data[].article_type` | string or null | The page's format, such as `ranked_list` or `comparison`. |
| `data[].source_type` | string or null | Who runs a publication, such as `editorial` or `review`: classed from the stored domain type and your competitors, as the Outreach board classes it (the Sources page can class a domain differently). Null for Reddit. |
| `data[].citations` | integer | Times AI answers cited it over the 90 days before `counts_as_of`. The counts, score and `last_cited_at` below share that window. |
| `data[].counts_as_of` | string | The refresh the counts are from: the board's latest, or for a target you started, finished or drafted that no longer appears, the last refresh that found it cited. |
| `data[].answers` | integer | Answers that cited it. |
| `data[].prompts` | integer | Prompts whose answers cited it. |
| `data[].platforms` | array of strings | Engines that cited it. |
| `data[].answers_naming_competitors_not_you` | integer | Answers that cited it and named a rival but not you. |
| `data[].answers_naming_no_brand` | integer | Answers that cited it and named no brand. |
| `data[].answers_naming_you` | integer | Answers that cited it and named you. |
| `data[].competitors_named` | array of objects | Up to five rivals named in the answers that cited it without naming you, most first. |
| `data[].competitors_named[].name` | string |  |
| `data[].competitors_named[].answers` | integer |  |
| `data[].opportunity_score` | number | 0-100, how the board ranks it: how often AI cites it, the answers there that miss you, how many engines and prompts cite it, and how recently; for a publication also its format. |
| `data[].tier` | string | The board's label for the score. |
| `data[].status` | string | One of `suggested`, `in_progress`, `done`, `dismissed`. |
| `data[].steps` | array of objects |  |
| `data[].steps[].text` | string |  |
| `data[].steps[].completed` | boolean |  |
| `data[].rules_url` | string or null | The subreddit's rules page. |
| `data[].last_cited_at` | string or null | RFC 3339 timestamp in UTC. The latest answer in the window that cited it. |
| `data[].started_at` | string or null | RFC 3339 timestamp in UTC. |
| `data[].completed_at` | string or null | RFC 3339 timestamp in UTC. |
| `data[].recommendation_id` | string or null | The Action Center recommendation this work counts toward; marking the target done moves it to done. |
| `data[].cooling_since` | string or null | RFC 3339 timestamp in UTC. When you last finished a target in this subreddit, if within 14 days: pace yourself before posting there again. Null on a finished target. |
| `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/BRAND_ID/outreach-targets" \
  -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) |
| 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) |