> ## 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.
# Watchlist search
**Interested in watchlist search?** The endpoint is coming soon. To request early access, email [support@bigdata.com](mailto:support@bigdata.com).
Watchlist search runs a query across a set of entities and returns the results grouped per entity.
Use it when you follow a portfolio, a sector or any list of companies and want to know what the same question surfaces for each of them. With `/v1/search` and a list of entities in an `any_of` filter, a handful of those entities with heavy coverage can take most of the chunks and the rest of the list gets little or nothing. Watchlist search distributes the chunks across the watchlist instead, so coverage is far more uniform.
Watchlist search is billed exactly like [`/v1/search`](./overview): by the number of chunks returned, counting each chunk once.
## Request
Send the entities in `watchlists`, the question in `query` and how many chunks you want in `max_chunks`:
```bash highlight={1} theme={null}
curl -X POST 'https://api.bigdata.com/v1/search/watchlist' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: ' \
--data '{
"watchlists": [
{ "entities": ["228D42", "D8442A", "4A6F00"] }
],
"max_chunks": { "value": 3, "per_entity": true },
"query": {
"text": "supply chain disruptions",
"filters": {
"timestamp": { "start": "2026-08-01T00:00:00Z", "end": "2026-09-01T00:00:00Z" }
}
}
}'
```
Entity ids come from the Knowledge Graph. Use [Find Entities](../knowledge_graph/introduction) to resolve a company name or ticker to its id.
### Watchlists
`watchlists` is a list of entity sets. Every set has its own `scope`, which decides where an entity must be detected for a chunk to count for it:
| `scope` | A chunk counts for the entity when it is detected... |
| --------------- | ---------------------------------------------------- |
| `all` (default) | anywhere in the document |
| `headline` | in the document headline |
| `body` | in the chunk text |
Mix scopes by sending several sets:
```json theme={null}
"watchlists": [
{ "entities": ["228D42", "D8442A"], "scope": "headline" },
{ "entities": ["4A6F00"], "scope": "body" }
]
```
Duplicate ids across sets are merged into a single group.
### Distributing the chunks
`max_chunks` controls both how many chunks come back and how they are shared:
| `max_chunks` | Behaviour | Limits |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `{ "value": 100 }` | `value` is a total budget. Chunks go to the entities with the most relevant matches, and a chunk is assigned to a single entity. | 1 to 512 with the reranker enabled (default); 1 to 1000 with `ranking_params.reranker.enabled: false` |
| `{ "value": 5, "per_entity": true }` | Up to `value` chunks for **every** entity. | 1 to 100 per entity, and `entities × value` at most 4000 |
When `max_chunks` is omitted, 100 chunks in total are spread across the watchlist.
Use the total budget when you want the most relevant content across the list and accept that some entities may come back empty. Use `per_entity` when you want a comparable amount of content for each entity, for example to build one card per company.
### Query
`query` takes the same `text`, `filters`, `ranking_params` and `auto_enrich_filters` as [`/v1/search`](./overview). Check [Query filters](./query_filters) for the available filters.
Three things differ from `/v1/search`:
* `max_chunks` lives at the top level, not inside `query`.
* `texts` and `external_search` are not supported.
* Results are always diversified across sources, so `ranking_params.content_diversification` cannot be set.
Sending any of these inside `query` returns a `400`.
## Response
`results` has one group per requested entity, in the order you sent them. Entities without matches are still present, with an empty `documents` list:
```json theme={null}
{
"results": [
{
"entity_id": "228D42",
"documents": [
{
"id": "57BB2AD919B94F4A86E3D3F7A2C4E1B0",
"headline": "Microsoft flags component shortages ahead of holiday quarter",
"timestamp": "2026-08-14T13:05:00Z",
"url": "https://example.com/microsoft-component-shortages",
"chunks": [
{
"cnum": 4,
"text": "The company said lead times for several server components had doubled since spring...",
"relevance": 0.81,
"rerank_relevance": 0.64
}
]
}
]
},
{
"entity_id": "D8442A",
"documents": [
{
"id": "0A9C3E7B21D64F0C9E2B5D8F1C6A7B34",
"headline": "Apple shifts more iPhone assembly to India as logistics costs climb",
"timestamp": "2026-08-20T07:40:00Z",
"url": "https://example.com/apple-india-assembly",
"chunks": [
{
"cnum": 2,
"text": "Apple is accelerating the move of assembly lines to India after freight rates rose for a third month...",
"relevance": 0.77,
"rerank_relevance": 0.58
}
]
}
]
},
{
"entity_id": "4A6F00",
"documents": []
}
],
"usage": {
"api_query_units": 0.2
},
"metadata": {
"request_id": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
"timestamp": "2026-09-10T09:12:46.019077+00:00"
}
}
```
Each document carries its `id`, `headline`, `timestamp`, `url` and the chunks assigned to that entity. A chunk is never returned under two entities: when a chunk mentions several watchlist entities it is attributed to one of them.
See the [API reference](/api-reference/search/search-watchlist) for the full request and response schema.