> ## Documentation Index
> Fetch the complete documentation index at: https://www.outx.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List All Watchlists

> One call that returns every watchlist your team owns, across all four types, so an agent can see what already exists before it creates or deletes.

`GET /api-watchlists` returns every watchlist the team owns: keyword, Reddit, people and company, in one response. Use it before creating anything, so you reuse or update an existing watchlist instead of adding a near-duplicate that eats a plan slot.

The per-type endpoints (`GET /api-keyword-watchlist` and friends) each list only their own type and carry the fuller detail for it. This one is the inventory.

## Query Parameters

<ParamField query="type" type="string | array">
  Restrict to one or more types. Allowed values: `keyword`, `reddit`, `people`, `company`. Pass several as comma-separated (`type=keyword,reddit`) or as repeated params. Omit for all four. An unrecognized value is rejected with a `400`.
</ParamField>

<ParamField query="disabled" type="boolean">
  `true` returns only paused watchlists, `false` only active ones. Omit for both.
</ParamField>

Any other query parameter is rejected with a `400` naming the offending parameter and the accepted list.

<RequestExample>
  ```bash All watchlists theme={null}
  curl -X GET \
    "https://api.outx.ai/api-watchlists" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```bash Active keyword and Reddit watchlists theme={null}
  curl -X GET \
    "https://api.outx.ai/api-watchlists?type=keyword,reddit&disabled=false" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.outx.ai/api-watchlists", {
    headers: { "x-api-key": "YOUR_API_KEY" },
  });

  const { data, count } = await response.json();
  const existing = data.find((w) => w.name === "Buying intent");
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.outx.ai/api-watchlists',
      headers={'x-api-key': 'YOUR_API_KEY'},
      params={'type': 'people'},
  )
  result = response.json()
  print(f"{result['count']} people watchlists")
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200 OK) theme={null}
  {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "keyword",
        "name": "Buying intent",
        "slug": "buying-intent-550e8400",
        "disabled": false,
        "created_at": "2026-08-20T09:14:02Z",
        "default_labels": ["buying-intent", "competitor-mention"]
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "type": "people",
        "name": "Target founders",
        "slug": "target-founders-770e8400",
        "disabled": false,
        "created_at": "2026-08-18T16:02:44Z"
      }
    ],
    "count": 2
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="data" type="array">
  The watchlists, newest first by `created_at`. Deleted watchlists are never included.
</ResponseField>

<ResponseField name="count" type="number">
  Number of entries in `data`. There is no paging on this endpoint, so it is the full total for the filters you sent.
</ResponseField>

### Watchlist Object Fields

<ResponseField name="id" type="string">
  Watchlist ID. Pass it to `GET /api-posts?watchlist_id=...` or to the matching typed endpoint.
</ResponseField>

<ResponseField name="type" type="string">
  One of `keyword`, `reddit`, `people`, `company`. This tells you which typed endpoint owns the watchlist: a keyword watchlist is read and updated at `/api-keyword-watchlist`, a people one at `/api-people-watchlist`, and so on. Asking the wrong endpoint for an ID returns `404`.
</ResponseField>

<ResponseField name="name" type="string">
  Watchlist name.
</ResponseField>

<ResponseField name="slug" type="string">
  URL-friendly slug. Changes only when the watchlist is renamed.
</ResponseField>

<ResponseField name="disabled" type="boolean">
  `true` when the watchlist is paused. A paused watchlist collects nothing. Resume it with `PUT` on its typed endpoint and `{ "disable": false }`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of creation.
</ResponseField>

<ResponseField name="default_labels" type="array">
  The label keys the watchlist opens on, which is what `labels=default` resolves to on [`GET /api-posts`](/docs/api-reference/engagement/posts/get). Empty when the watchlist has no defaults, which is common: there `labels=default` filters nothing, so read the watchlist's label set and choose keys explicitly.

  **Present on `keyword` and `reddit` rows only.** People and company watchlists have no intent labels, so the field is absent from those rows entirely rather than empty.
</ResponseField>

## Error Responses

| Status Code | Error Message                     | Description                                                                                  |
| ----------- | --------------------------------- | -------------------------------------------------------------------------------------------- |
| 400         | Invalid value(s) for type         | `type` held something other than `keyword`, `reddit`, `people` or `company`                  |
| 400         | Unknown query parameter(s)        | An unrecognized parameter was sent. The response names it and lists the accepted parameters. |
| 401         | Missing API Key / Invalid API Key | Missing or invalid `x-api-key` header                                                        |

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why does this exist when each type already has a list endpoint?">
    To answer "what do we already have" in one call instead of four. An agent that has to find a watchlist by name, check whether a signal is already covered, or clean up a test list would otherwise call every typed endpoint and merge the results.
  </Accordion>

  <Accordion title="Does it return the keywords, profiles or labels of each watchlist?">
    No. It returns the identity of each watchlist plus `default_labels` on the labelled types. For keywords, profiles, companies, the objective or the full label set, call the typed endpoint with `?id=`, for example [`GET /api-keyword-watchlist?id=...`](/docs/api-reference/watchlist/keyword/get).
  </Accordion>

  <Accordion title="Is there a limit on how many it returns?">
    No paging and no cap. `count` is the number of rows in `data`.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Design your watchlists" icon="compass-drafting" href="/docs/api-reference/concepts/design-your-watchlists">
    How to lay watchlists out before you create them
  </Card>

  <Card title="Choose a watchlist type" icon="list-check" href="/docs/api-reference/watchlist/overview">
    The four types side by side
  </Card>
</CardGroup>