> ## 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_watchlist_search > Search saved watchlists or inline entity lists and return fast-search results grouped by entity. ## 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: ```json title="Search two companies for supply-chain disruptions" theme={null} { "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`](/mcp-reference/tools/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: ```json theme={null} { "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 ```json title="Watchlist Search response" theme={null} { "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 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.