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

# bigdata_get_watchlist

> List the watchlists you own, or fetch one watchlist by ID with its companies and securities.

## Overview

The `bigdata_get_watchlist` tool reads watchlists from your Bigdata.com account. It has two modes depending on whether you pass an `id`:

* **List mode** (no `id`): returns the watchlists the caller owns, with name and description only. Shared, public, and global watchlists are not included.
* **Fetch mode** (with `id`): returns one watchlist the caller can read, including shared watchlists when the ID is known, together with the Knowledge Graph IDs in `items`.

## When to Use

Get Watchlist is ideal for:

* **Discovering watchlists:** Finding out which watchlists exist before editing, deleting, or analyzing one
* **Loading holdings:** Retrieving the entity IDs of a watchlist to pass to [`bigdata_portfolio_tearsheet`](/mcp-reference/tools/bigdata-portfolio-tearsheet) or to build [`bigdata_search`](/mcp-reference/tools/bigdata-search) filters
* **Resolving an ID:** Turning a watchlist name into the `id` required by [`bigdata_edit_watchlist`](/mcp-reference/tools/bigdata-edit-watchlist) and [`bigdata_delete_watchlist`](/mcp-reference/tools/bigdata-delete-watchlist)

<Tip>
  Never guess a watchlist ID. Call the tool without an `id` first to list owned watchlists, or take the ID from the watchlist URL in the Bigdata App.
</Tip>

## How It Works

1. **List** owned watchlists by calling the tool without an `id`
2. **Pick** the watchlist by name and take its `id`
3. **Fetch** it by calling the tool again with that `id` to load `items`
4. **Use** the returned IDs with other tools, for example a portfolio tearsheet across the whole list

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | No | Watchlist ID. Omit to list the watchlists you own. Provide it to fetch a single watchlist, including shared watchlists you can read. |

### Important Notes

* List mode returns metadata only. Make a second call with an `id` to get the entity IDs
* List mode only shows watchlists you own. A watchlist shared with you can still be fetched by ID
* Watchlists created in the Bigdata App can hold more than 100 items, and fetch mode returns all of them
* An unknown ID returns an error, for example `Watchlist <id> not found`

## Data Returned

Both modes return a JSON object with a `watchlists` array.

| Field | List mode | Fetch mode | Description |
| - | :-: | :-: | - |
| `id` | Yes | Yes | Watchlist ID |
| `name` | Yes | Yes | Display name |
| `description` | Yes | Yes | Description, or `null` when none was set |
| `items` | No | Yes | Knowledge Graph IDs of the companies and securities on the watchlist |

**List mode example**

```json theme={null}
{
  "watchlists": [
    {
      "id": "b52f3bc1-95d8-4869-8aa3-a7cbdf31c164",
      "name": "My Portfolio",
      "description": "Imported from Google Sheet portfolio (8 holdings, resolved by ISIN)"
    }
  ]
}
```

**Fetch mode example**

```json theme={null}
{
  "watchlists": [
    {
      "id": "ea4c5039-6edb-45c1-9c51-37d3ab9689b0",
      "name": "US mega-cap tech",
      "description": "Core large-cap technology holdings",
      "items": ["228D42", "D8442A"]
    }
  ]
}
```

## Usage Monitoring

The tool `bigdata_get_watchlist` does not consume any quota.

## Practical Tips

### From watchlist to analysis

Pass `items` straight into [`bigdata_portfolio_tearsheet`](/mcp-reference/tools/bigdata-portfolio-tearsheet) for a consolidated grid, or into the entity filters of [`bigdata_search`](/mcp-reference/tools/bigdata-search) to search news, filings, and transcripts across the whole watchlist.

### Presenting results

Show the watchlist name and item count first, then the securities. To display names and tickers rather than raw IDs, resolve them through the portfolio tearsheet, whose identity columns always include company name and ticker.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.