Watchlist search

Interested in watchlist search? The endpoint is coming soon. To request early access, email 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: 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:

curl -X POST 'https://api.bigdata.com/v1/search/watchlist' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: <your-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 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:

"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. Check 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:

{
  "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 for the full request and response schema.

Getting Started

Research Service

Search Service

Monitors

Upload proprietary content

Knowledge Graph

Watchlist

Troubleshooting

Request

Watchlists

Distributing the chunks

Query

Response

​Request

​Watchlists

​Distributing the chunks

​Query

​Response

Request

Watchlists

Distributing the chunks

Query

Response