bigdata_watchlist_search

Overview

The Watchlist Search MCP tool (bigdata_watchlist_search) runs one search across a saved watchlist, an inline list of Knowledge Graph entity IDs, or both. Results are grouped by entity in the order requested, so every company keeps its place even when no matching documents are found. By default, the tool returns up to five chunks per entity. This makes it useful when you want comparable coverage across a portfolio instead of allowing a few heavily covered companies to consume the whole result budget.

When to Use

Watchlist Search is ideal for:

Portfolio research: Run the same question across every company in a portfolio or watchlist
Balanced research: Reserve a result budget for each company so heavily covered names do not crowd out the rest
Saved-watchlist workflows: Search a watchlist by ID without copying its entities into the request
Cross-company screening: Apply the same date, source, document type, sentiment, or other filters to a whole list

Request

The request object is required:

Search two companies for supply-chain disruptions

{
  "request": {
    "watchlists": [
      {
        "entities": ["4A6F00", "E09E2B"],
        "scope": "ALL"
      }
    ],
    "max_chunks": {
      "value": 5,
      "per_entity": true
    },
    "query": {
      "text": "supply chain disruptions",
      "filters": {
        "timestamp": {
          "start": "2026-01-01T00:00:00Z"
        }
      }
    }
  }
}

Field	Type	Required	Description
`request.watchlists`	array	Yes	One or more saved or inline watchlists.
`request.max_chunks`	object or `null`	No	Controls the number of chunks and whether the budget applies per entity or across the whole request.
`request.query`	object	Yes	Search text, filters, or both.

Watchlists

Every item in request.watchlists must contain exactly one of:

id: A saved watchlist ID, which you can obtain from bigdata_get_watchlist.
entities: A non-empty array of Knowledge Graph entity IDs.

Each item can also set scope, which determines where its entities must occur:

`scope`	Meaning
`ALL`	The entity can occur anywhere in the document. This is the default.
`HEADLINE`	The entity must occur in the headline.
`BODY`	The entity must occur in the document body.

Lowercase scope values are normalized, but the published schema uses uppercase values. Saved and inline lists can be combined:

{
  "watchlists": [
    {
      "id": "b52f3bc1-95d8-4869-8aa3-a7cbdf31c164",
      "scope": "ALL"
    },
    {
      "entities": ["4A6F00", "E09E2B"],
      "scope": "HEADLINE"
    }
  ]
}

Duplicate entities are merged, preserving the order in which they were first requested. A missing, inaccessible, or empty saved watchlist causes the search to fail rather than silently contributing an empty list.

Chunk budgets

max_chunks controls both the result limit and how chunks are distributed:

Input	Behavior	Limits
Omitted	Up to 5 chunks per entity	Up to 100 per entity; entity count × 5 cannot exceed 4,000
`{ "value": 5, "per_entity": true }`	Up to 5 chunks for every entity	`value` up to 100; entity count × `value` cannot exceed 4,000
`{ "value": 5 }`	5 chunks shared by the whole list	`value` up to 512
`{ "value": 5, "per_entity": false }`	5 chunks shared by the whole list	`value` up to 512

value must always be at least 1. Use a per-entity budget for even portfolio coverage. Use a shared budget when you want the strongest matches across the entire list and accept that some entities may receive no result.

Query

request.query accepts:

text: Optional natural-language query, 4–1,400 characters
filters: Optional filter object

Provide at least one effective text value or filter. A filter-only query is valid. Unknown query fields are rejected. The following bigdata_search options are not supported: search_mode, texts, reranker_text, ranking_params, external_search, response_detail, and query-level max_chunks.

Filters

Filters go inside request.query.filters and can be combined:

Filter	Description
`entity`	Entity mentions using `search_in` (`ALL`, `HEADLINE`, or `BODY`) and optional `all_of`, `any_of`, or `none_of` ID arrays.
`keyword`	Keywords using the same `search_in`, `all_of`, `any_of`, and `none_of` shape. Each keyword must contain at least 3 characters.
`timestamp`	ISO 8601 `start` and/or `end`. `start` must not be later than `end`.
`category`	`mode` (`INCLUDE` or `EXCLUDE`) and category `values`.
`document_type`	Include or exclude filings, investment research, news, transcripts, or transcript presentations. Supported typed objects can also specify filing, research, or transcript subtypes.
`reporting_entities`	Entity IDs for the companies that authored or filed the documents.
`reporting_periods`	Objects containing `fiscal_year` (1 or greater), `fiscal_quarter` (1–4), or both.
`sentiment`	Either `values` (`positive`, `negative`, or `neutral`) or `ranges` with `min` and `max` from -1 to 1.
`tag`	`any_of` values matched exactly against private-document tags.
`source`	`mode` and 1–500 source IDs.
`original_language`	`mode` and 1–500 language codes, each 2–16 characters.
`sections`	`any_of` containing `MANAGEMENT-DISCUSSION` and/or `QUESTION-ANSWER`.
`authors`	`type` (`company`, `person`, or `position`) and a list of values.
`speakers`	`type` (`company`, `person`, or `position`) and a list of values.

The combined number of entity, keyword, reporting-entity, and tag filter values cannot exceed 500. Entity IDs in filters must be non-empty strings.

Response

Watchlist Search response

{
  "results": [
    {
      "entity_id": "4A6F00",
      "documents": [
        {
          "id": "C4DE57322229958E1E92791D4DBEE1C9",
          "headline": "Alphabet Inc. files FORM 10-K for FY 2025 on Feb 5, 2026",
          "timestamp": "2026-02-05T05:00:00Z",
          "url": "https://app.bigdata.com/documents/C4DE57322229958E1E92791D4DBEE1C9?cnum=52",
          "source": {
            "name": "Edgar SEC Filings"
          },
          "chunks": [
            {
              "cnum": 52,
              "text": "We have experienced and may in the future experience supply shortages, price increases, quality issues, or longer lead times that could harm our operations... A significant supply interruption that affects us or our vendors could delay critical data center or network infrastructure upgrades or expansions and delay consumer product availability."
            }
          ]
        }
      ]
    },
    {
      "entity_id": "E09E2B",
      "documents": [
        {
          "id": "EF79F39CABD51894A984992B4E9DD50D",
          "headline": "NVIDIA CORP files FORM 10-Q for Q1, FY 2027 on May 20, 2026",
          "timestamp": "2026-05-20T20:35:52Z",
          "url": "https://app.bigdata.com/documents/EF79F39CABD51894A984992B4E9DD50D?cnum=105",
          "source": {
            "name": "Edgar SEC Filings"
          },
          "chunks": [
            {
              "cnum": 105,
              "text": "We continue to increase our supply and capacity purchases with existing and new suppliers to support our demand projections and increasing complexity of our data center products... Delays or shortfalls could impact our ability to meet demand."
            }
          ]
        }
      ]
    }
  ],
  "resolved_watchlists": null,
  "metadata": {
    "usage": {
      "api_query_units": 1.0
    },
    "request_id": "661023e2-ced5-496e-bcd1-0e5605284e56",
    "timestamp": "2026-10-06T09:12:47.684115+00:00"
  }
}

The response guarantees:

One result group per requested entity, in request order
An empty documents array for an entity that received no documents
Each chunk assigned to only one entity, even when it mentions several
source and timestamp may be null
No relevance scores or live-web documents

MCP Reference

Tools

Official MCP Integrations

Custom MCP Integrations

Plugins

Prompt examples

Evals

Overview

When to Use

Request

Watchlists

Chunk budgets

Query

Filters

Response

​Overview

​When to Use

​Request

​Watchlists

​Chunk budgets

​Query

​Filters

​Response

Overview

When to Use

Request

Watchlists

Chunk budgets

Query

Filters

Response