> ## 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 Company Watchlists

> Retrieve all company watchlists or a specific watchlist by ID

Retrieve your company watchlists with detailed information about tracked companies.

<Note>
  **Platform: LinkedIn only.** Company watchlists track LinkedIn company pages; there is no Reddit equivalent. Collection requires your team's OutX Chrome extension to be installed and active (within the last 48 hours). See [Choose a watchlist type](/docs/api-reference/watchlist/overview).
</Note>

## Query Parameters

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

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

  ```bash Get Specific Watchlist theme={null}
  curl -X GET \
    "https://api.outx.ai/api-company-watchlist?id=880e8400-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-company-watchlist',
    {
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    }
  );

  // Get specific watchlist
  const watchlistId = '880e8400-e29b-41d4-a716-446655440000';
  const specificResponse = await fetch(
    `https://api.outx.ai/api-company-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-company-watchlist',
      headers=headers
  )

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

<ResponseExample>
  ```json All Watchlists theme={null}
  {
    "watchlists": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440000",
        "name": "FAANG Companies",
        "slug": "faang-companies-880e8400",
        "type": "company",
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "count": 1
  }
  ```

  ```json Single Watchlist theme={null}
  {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "name": "FAANG Companies",
    "slug": "faang-companies-880e8400",
    "type": "company",
    "companies_count": 5,
    "lists": [
      {
        "id": "list-uuid",
        "name": "List Name"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="watchlists" type="array">
  Array of watchlist objects (when fetching all)
</ResponseField>

<ResponseField name="count" type="number">
  Total number of watchlists (when fetching all)
</ResponseField>

<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
</ResponseField>

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

<ResponseField name="companies_count" type="number">
  Number of tracked companies
</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 company watchlists?">
    To get all company watchlists, call `GET /api-company-watchlist` without any parameters. To get a specific watchlist, pass the watchlist ID as a query parameter: `GET /api-company-watchlist?id=YOUR_WATCHLIST_ID`. The single-watchlist response includes additional details like `companies_count` and associated `lists`.
  </Accordion>

  <Accordion title="What fields are returned in the response?">
    When fetching all watchlists, you get a summary array with `id`, `name`, `slug`, `type`, and `createdAt` for each watchlist, plus a total `count`. When fetching a single watchlist by ID, you also get `companies_count` (number of tracked companies) and the `lists` array with associated list details.
  </Accordion>
</AccordionGroup>