> ## 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.

# Get Keyword Watchlists

> Retrieve all keyword watchlists or a specific watchlist by ID

Retrieve your keyword watchlists with detailed information about tracked keywords and filtering rules.

<Note>
  **Platform: LinkedIn.** This endpoint lists LinkedIn keyword watchlists only. Reddit watchlists live behind [`GET /api-reddit-watchlist`](/docs/api-reference/watchlist/reddit/get). To list everything your team tracks, call each type's GET endpoint. See [Choose a watchlist type](/docs/api-reference/watchlist/overview).
</Note>

To fetch the actual posts collected by a watchlist, use [`GET /api-posts`](/docs/api-reference/engagement/posts/get) with the watchlist's `id` as `watchlist_id`.

## Query Parameters

<ParamField query="id" type="string">
  Watchlist ID. If omitted, returns all watchlists for your team.
</ParamField>

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

  ```bash Get Specific Watchlist theme={null}
  curl -X GET \
    "https://api.outx.ai/api-keyword-watchlist?id=550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: YOUR_API_KEY"
  ```

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

  // Get specific watchlist
  const watchlistId = "550e8400-e29b-41d4-a716-446655440000";
  const specificResponse = await fetch(
    `https://api.outx.ai/api-keyword-watchlist?id=${watchlistId}`,
    {
      headers: { "x-api-key": "YOUR_API_KEY" },
    }
  );
  ```

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

  headers = {'x-api-key': 'YOUR_API_KEY'}

  # Get all watchlists
  response = requests.get(
      'https://api.outx.ai/api-keyword-watchlist',
      headers=headers
  )

  # Get specific watchlist
  watchlist_id = '550e8400-e29b-41d4-a716-446655440000'
  specific_response = requests.get(
      f'https://api.outx.ai/api-keyword-watchlist?id={watchlist_id}',
      headers=headers
  )
  ```
</RequestExample>

<ResponseExample>
  ```json All Watchlists theme={null}
  {
    "watchlists": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Remote Senior Jobs",
        "slug": "remote-senior-jobs-550e8400",
        "type": "keyword",
        "fetchFreqInHours": 6,
        "keywords": ["hiring", "job opening"],
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "count": 1
  }
  ```

  ```json Single Watchlist theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Remote Senior Jobs",
    "slug": "remote-senior-jobs-550e8400",
    "type": "keyword",
    "keywords": ["hiring", "job opening"],
    "fetchFreqInHours": 6,
    "objective": "Find companies actively hiring senior remote engineers",
    "prompt": null,
    "disabled": false,
    "slack_webhook_url": null,
    "last_synced_at": "2026-07-14T22:10:05Z",
    "labels": [
      { "key": "hiring", "description": "Job postings for senior engineering roles", "default": true },
      { "key": "industry-news", "description": "Hiring-market news and layoffs", "default": false }
    ],
    "keyword_tracking": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "primary_keyword": "hiring",
        "required_keywords": ["remote", "senior", "engineer"],
        "excluded_keywords": ["unpaid", "intern"],
        "include_all_required": true,
        "last_synced_at": "2026-07-14T22:10:05Z"
      }
    ]
  }
  ```
</ResponseExample>

## Response Fields (All Watchlists)

<ResponseField name="watchlists" type="array">
  Array of watchlist objects
</ResponseField>

<ResponseField name="count" type="number">
  Total number of watchlists
</ResponseField>

## Response Fields (Single Watchlist)

<ResponseField name="id" type="string">
  Unique identifier for the watchlist
</ResponseField>

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

<ResponseField name="slug" type="string">
  URL-friendly slug for the watchlist
</ResponseField>

<ResponseField name="type" type="string">
  Always "keyword" for keyword watchlists
</ResponseField>

<ResponseField name="keywords" type="array">
  Array of tracked keywords
</ResponseField>

<ResponseField name="fetchFreqInHours" type="number">
  Fetch frequency in hours
</ResponseField>

<ResponseField name="objective" type="string | null">
  One-sentence objective used to score post relevance. `null` on watchlists created without one (a generated objective may appear a few seconds after create).
</ResponseField>

<ResponseField name="prompt" type="string | null">
  The natural-language prompt the watchlist was generated from, if any.
</ResponseField>

<ResponseField name="disabled" type="boolean">
  Whether the watchlist is paused. A disabled watchlist collects nothing, and `PUT` requests against it return `409` until it is re-enabled with `disable: false`.
</ResponseField>

<ResponseField name="slack_webhook_url" type="string | null">
  Slack webhook the watchlist notifies, if set.
</ResponseField>

<ResponseField name="last_synced_at" type="string | null">
  ISO 8601 timestamp of the last completed fetch cycle. `null` if the watchlist has never synced.
</ResponseField>

<ResponseField name="labels" type="array">
  Intent labels on the watchlist, as `{ key, description, default }` objects. Labels with `default: true` (at most 2) are the watchlist's default feed filters. Read this before patching `labels` so you can preserve current defaults. See [Intent labels & defaults](/docs/api-reference/concepts/intent-labels).
</ResponseField>

<ResponseField name="keyword_tracking" type="array">
  Detailed tracking configuration for each keyword: `id`, `primary_keyword`, `required_keywords`, `excluded_keywords`, `include_all_required`, `last_synced_at`. Only on the single-watchlist response.
</ResponseField>

## Error Responses

| Status Code | Error Message                        | Description                                  |
| ----------- | ------------------------------------ | -------------------------------------------- |
| 401         | Unauthorized                         | Invalid or missing API key                   |
| 403         | Access denied                        | Trying to access watchlist from another team |
| 404         | Watchlist not found or access denied | Watchlist ID doesn't exist                   |

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I get a specific watchlist versus all my watchlists?">
    To get all keyword watchlists, call `GET /api-keyword-watchlist` without any parameters. To get a specific watchlist, pass the watchlist ID as a query parameter: `GET /api-keyword-watchlist?id=YOUR_WATCHLIST_ID`. The single-watchlist response includes more detail, such as the `keyword_tracking` array with full filtering rules.
  </Accordion>

  <Accordion title="What fields are returned in the response?">
    When fetching all watchlists, you get a summary for each one including `id`, `name`, `slug`, `type`, `fetchFreqInHours`, `keywords`, and `createdAt`. When fetching a single watchlist by ID, you also get the `keyword_tracking` array, which contains detailed filtering configuration for each keyword including `required_keywords` and `excluded_keywords`.
  </Accordion>
</AccordionGroup>