Search watchlist
curl --request POST \
--url https://api.bigdata.com/v1/search/watchlist \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"watchlists": [
{
"entities": [
"228D42",
"D8442A"
],
"scope": "all"
}
],
"query": {
"text": "supply chain disruptions",
"filters": {
"timestamp": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"sentiment": {
"ranges": [
{
"min": -1,
"max": -0.3
},
{
"min": 0.3,
"max": 1
}
],
"values": []
},
"reporting_entities": [
"228D42"
],
"reporting_periods": [
{
"fiscal_year": 2024,
"fiscal_quarter": 3
}
],
"authors": {
"type": "person",
"values": [
"4L0FDS"
]
},
"speakers": {
"type": "company",
"values": [
"DF67D7"
]
}
},
"ranking_params": {
"source_boost": 1,
"freshness_boost": 1
},
"auto_enrich_filters": true
},
"search_mode": "fast"
}
'import requests
url = "https://api.bigdata.com/v1/search/watchlist"
payload = {
"watchlists": [
{
"entities": ["228D42", "D8442A"],
"scope": "all"
}
],
"query": {
"text": "supply chain disruptions",
"filters": {
"timestamp": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"sentiment": {
"ranges": [
{
"min": -1,
"max": -0.3
},
{
"min": 0.3,
"max": 1
}
],
"values": []
},
"reporting_entities": ["228D42"],
"reporting_periods": [
{
"fiscal_year": 2024,
"fiscal_quarter": 3
}
],
"authors": {
"type": "person",
"values": ["4L0FDS"]
},
"speakers": {
"type": "company",
"values": ["DF67D7"]
}
},
"ranking_params": {
"source_boost": 1,
"freshness_boost": 1
},
"auto_enrich_filters": True
},
"search_mode": "fast"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
watchlists: [{entities: ['228D42', 'D8442A'], scope: 'all'}],
query: {
text: 'supply chain disruptions',
filters: {
timestamp: {start: '2023-11-07T05:31:56Z', end: '2023-11-07T05:31:56Z'},
sentiment: {ranges: [{min: -1, max: -0.3}, {min: 0.3, max: 1}], values: []},
reporting_entities: ['228D42'],
reporting_periods: [{fiscal_year: 2024, fiscal_quarter: 3}],
authors: {type: 'person', values: ['4L0FDS']},
speakers: {type: 'company', values: ['DF67D7']}
},
ranking_params: {source_boost: 1, freshness_boost: 1},
auto_enrich_filters: true
},
search_mode: 'fast'
})
};
fetch('https://api.bigdata.com/v1/search/watchlist', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bigdata.com/v1/search/watchlist",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'watchlists' => [
[
'entities' => [
'228D42',
'D8442A'
],
'scope' => 'all'
]
],
'query' => [
'text' => 'supply chain disruptions',
'filters' => [
'timestamp' => [
'start' => '2023-11-07T05:31:56Z',
'end' => '2023-11-07T05:31:56Z'
],
'sentiment' => [
'ranges' => [
[
'min' => -1,
'max' => -0.3
],
[
'min' => 0.3,
'max' => 1
]
],
'values' => [
]
],
'reporting_entities' => [
'228D42'
],
'reporting_periods' => [
[
'fiscal_year' => 2024,
'fiscal_quarter' => 3
]
],
'authors' => [
'type' => 'person',
'values' => [
'4L0FDS'
]
],
'speakers' => [
'type' => 'company',
'values' => [
'DF67D7'
]
]
],
'ranking_params' => [
'source_boost' => 1,
'freshness_boost' => 1
],
'auto_enrich_filters' => true
],
'search_mode' => 'fast'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bigdata.com/v1/search/watchlist"
payload := strings.NewReader("{\n \"watchlists\": [\n {\n \"entities\": [\n \"228D42\",\n \"D8442A\"\n ],\n \"scope\": \"all\"\n }\n ],\n \"query\": {\n \"text\": \"supply chain disruptions\",\n \"filters\": {\n \"timestamp\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"sentiment\": {\n \"ranges\": [\n {\n \"min\": -1,\n \"max\": -0.3\n },\n {\n \"min\": 0.3,\n \"max\": 1\n }\n ],\n \"values\": []\n },\n \"reporting_entities\": [\n \"228D42\"\n ],\n \"reporting_periods\": [\n {\n \"fiscal_year\": 2024,\n \"fiscal_quarter\": 3\n }\n ],\n \"authors\": {\n \"type\": \"person\",\n \"values\": [\n \"4L0FDS\"\n ]\n },\n \"speakers\": {\n \"type\": \"company\",\n \"values\": [\n \"DF67D7\"\n ]\n }\n },\n \"ranking_params\": {\n \"source_boost\": 1,\n \"freshness_boost\": 1\n },\n \"auto_enrich_filters\": true\n },\n \"search_mode\": \"fast\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bigdata.com/v1/search/watchlist")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"watchlists\": [\n {\n \"entities\": [\n \"228D42\",\n \"D8442A\"\n ],\n \"scope\": \"all\"\n }\n ],\n \"query\": {\n \"text\": \"supply chain disruptions\",\n \"filters\": {\n \"timestamp\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"sentiment\": {\n \"ranges\": [\n {\n \"min\": -1,\n \"max\": -0.3\n },\n {\n \"min\": 0.3,\n \"max\": 1\n }\n ],\n \"values\": []\n },\n \"reporting_entities\": [\n \"228D42\"\n ],\n \"reporting_periods\": [\n {\n \"fiscal_year\": 2024,\n \"fiscal_quarter\": 3\n }\n ],\n \"authors\": {\n \"type\": \"person\",\n \"values\": [\n \"4L0FDS\"\n ]\n },\n \"speakers\": {\n \"type\": \"company\",\n \"values\": [\n \"DF67D7\"\n ]\n }\n },\n \"ranking_params\": {\n \"source_boost\": 1,\n \"freshness_boost\": 1\n },\n \"auto_enrich_filters\": true\n },\n \"search_mode\": \"fast\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bigdata.com/v1/search/watchlist")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"watchlists\": [\n {\n \"entities\": [\n \"228D42\",\n \"D8442A\"\n ],\n \"scope\": \"all\"\n }\n ],\n \"query\": {\n \"text\": \"supply chain disruptions\",\n \"filters\": {\n \"timestamp\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"sentiment\": {\n \"ranges\": [\n {\n \"min\": -1,\n \"max\": -0.3\n },\n {\n \"min\": 0.3,\n \"max\": 1\n }\n ],\n \"values\": []\n },\n \"reporting_entities\": [\n \"228D42\"\n ],\n \"reporting_periods\": [\n {\n \"fiscal_year\": 2024,\n \"fiscal_quarter\": 3\n }\n ],\n \"authors\": {\n \"type\": \"person\",\n \"values\": [\n \"4L0FDS\"\n ]\n },\n \"speakers\": {\n \"type\": \"company\",\n \"values\": [\n \"DF67D7\"\n ]\n }\n },\n \"ranking_params\": {\n \"source_boost\": 1,\n \"freshness_boost\": 1\n },\n \"auto_enrich_filters\": true\n },\n \"search_mode\": \"fast\"\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"entity_id": "228D42",
"documents": [
{
"id": "57BB2AD919....",
"headline": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call",
"chunks": [
{
"cnum": 7,
"text": "Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below.\nMSFT Price Action: Microsoft stock is up 5.5% to $417.17 year-over-year in after-hours trading Wednesday versus a 52-week trading range of $344.79 to $468.35.",
"relevance": 0.8949412447701082,
"rerank_relevance": 0.6432
}
],
"timestamp": "2025-04-30T21:30:00Z",
"url": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack"
}
]
}
],
"usage": {
"api_query_units": 0.7
},
"metadata": {
"request_id": "user_2k3Z4SerTUIieyCfQhGR5UF2Af3",
"timestamp": "2025-09-12T11:10:46.019077+00:00"
}
}Search
Search watchlist
Run a query across a watchlist of entities and get the results grouped per entity.
With /v1/search and a list of entities in an any_of filter, a handful of those entities can take most of the chunks. Watchlist search distributes the chunks across the watchlist instead: either a total budget spread over the entities (max_chunks.per_entity: false) or a fixed number of chunks for every entity (max_chunks.per_entity: true), so coverage of the watchlist is far more uniform. A chunk is assigned to a single entity, and results are always diversified across sources.
The response carries one group per requested entity, in request order; entities without matches come back with an empty documents list. Billing is the same as /v1/search.
POST
/
v1
/
search
/
watchlist
Search watchlist
curl --request POST \
--url https://api.bigdata.com/v1/search/watchlist \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"watchlists": [
{
"entities": [
"228D42",
"D8442A"
],
"scope": "all"
}
],
"query": {
"text": "supply chain disruptions",
"filters": {
"timestamp": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"sentiment": {
"ranges": [
{
"min": -1,
"max": -0.3
},
{
"min": 0.3,
"max": 1
}
],
"values": []
},
"reporting_entities": [
"228D42"
],
"reporting_periods": [
{
"fiscal_year": 2024,
"fiscal_quarter": 3
}
],
"authors": {
"type": "person",
"values": [
"4L0FDS"
]
},
"speakers": {
"type": "company",
"values": [
"DF67D7"
]
}
},
"ranking_params": {
"source_boost": 1,
"freshness_boost": 1
},
"auto_enrich_filters": true
},
"search_mode": "fast"
}
'import requests
url = "https://api.bigdata.com/v1/search/watchlist"
payload = {
"watchlists": [
{
"entities": ["228D42", "D8442A"],
"scope": "all"
}
],
"query": {
"text": "supply chain disruptions",
"filters": {
"timestamp": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"sentiment": {
"ranges": [
{
"min": -1,
"max": -0.3
},
{
"min": 0.3,
"max": 1
}
],
"values": []
},
"reporting_entities": ["228D42"],
"reporting_periods": [
{
"fiscal_year": 2024,
"fiscal_quarter": 3
}
],
"authors": {
"type": "person",
"values": ["4L0FDS"]
},
"speakers": {
"type": "company",
"values": ["DF67D7"]
}
},
"ranking_params": {
"source_boost": 1,
"freshness_boost": 1
},
"auto_enrich_filters": True
},
"search_mode": "fast"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
watchlists: [{entities: ['228D42', 'D8442A'], scope: 'all'}],
query: {
text: 'supply chain disruptions',
filters: {
timestamp: {start: '2023-11-07T05:31:56Z', end: '2023-11-07T05:31:56Z'},
sentiment: {ranges: [{min: -1, max: -0.3}, {min: 0.3, max: 1}], values: []},
reporting_entities: ['228D42'],
reporting_periods: [{fiscal_year: 2024, fiscal_quarter: 3}],
authors: {type: 'person', values: ['4L0FDS']},
speakers: {type: 'company', values: ['DF67D7']}
},
ranking_params: {source_boost: 1, freshness_boost: 1},
auto_enrich_filters: true
},
search_mode: 'fast'
})
};
fetch('https://api.bigdata.com/v1/search/watchlist', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bigdata.com/v1/search/watchlist",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'watchlists' => [
[
'entities' => [
'228D42',
'D8442A'
],
'scope' => 'all'
]
],
'query' => [
'text' => 'supply chain disruptions',
'filters' => [
'timestamp' => [
'start' => '2023-11-07T05:31:56Z',
'end' => '2023-11-07T05:31:56Z'
],
'sentiment' => [
'ranges' => [
[
'min' => -1,
'max' => -0.3
],
[
'min' => 0.3,
'max' => 1
]
],
'values' => [
]
],
'reporting_entities' => [
'228D42'
],
'reporting_periods' => [
[
'fiscal_year' => 2024,
'fiscal_quarter' => 3
]
],
'authors' => [
'type' => 'person',
'values' => [
'4L0FDS'
]
],
'speakers' => [
'type' => 'company',
'values' => [
'DF67D7'
]
]
],
'ranking_params' => [
'source_boost' => 1,
'freshness_boost' => 1
],
'auto_enrich_filters' => true
],
'search_mode' => 'fast'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bigdata.com/v1/search/watchlist"
payload := strings.NewReader("{\n \"watchlists\": [\n {\n \"entities\": [\n \"228D42\",\n \"D8442A\"\n ],\n \"scope\": \"all\"\n }\n ],\n \"query\": {\n \"text\": \"supply chain disruptions\",\n \"filters\": {\n \"timestamp\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"sentiment\": {\n \"ranges\": [\n {\n \"min\": -1,\n \"max\": -0.3\n },\n {\n \"min\": 0.3,\n \"max\": 1\n }\n ],\n \"values\": []\n },\n \"reporting_entities\": [\n \"228D42\"\n ],\n \"reporting_periods\": [\n {\n \"fiscal_year\": 2024,\n \"fiscal_quarter\": 3\n }\n ],\n \"authors\": {\n \"type\": \"person\",\n \"values\": [\n \"4L0FDS\"\n ]\n },\n \"speakers\": {\n \"type\": \"company\",\n \"values\": [\n \"DF67D7\"\n ]\n }\n },\n \"ranking_params\": {\n \"source_boost\": 1,\n \"freshness_boost\": 1\n },\n \"auto_enrich_filters\": true\n },\n \"search_mode\": \"fast\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bigdata.com/v1/search/watchlist")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"watchlists\": [\n {\n \"entities\": [\n \"228D42\",\n \"D8442A\"\n ],\n \"scope\": \"all\"\n }\n ],\n \"query\": {\n \"text\": \"supply chain disruptions\",\n \"filters\": {\n \"timestamp\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"sentiment\": {\n \"ranges\": [\n {\n \"min\": -1,\n \"max\": -0.3\n },\n {\n \"min\": 0.3,\n \"max\": 1\n }\n ],\n \"values\": []\n },\n \"reporting_entities\": [\n \"228D42\"\n ],\n \"reporting_periods\": [\n {\n \"fiscal_year\": 2024,\n \"fiscal_quarter\": 3\n }\n ],\n \"authors\": {\n \"type\": \"person\",\n \"values\": [\n \"4L0FDS\"\n ]\n },\n \"speakers\": {\n \"type\": \"company\",\n \"values\": [\n \"DF67D7\"\n ]\n }\n },\n \"ranking_params\": {\n \"source_boost\": 1,\n \"freshness_boost\": 1\n },\n \"auto_enrich_filters\": true\n },\n \"search_mode\": \"fast\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bigdata.com/v1/search/watchlist")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"watchlists\": [\n {\n \"entities\": [\n \"228D42\",\n \"D8442A\"\n ],\n \"scope\": \"all\"\n }\n ],\n \"query\": {\n \"text\": \"supply chain disruptions\",\n \"filters\": {\n \"timestamp\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"sentiment\": {\n \"ranges\": [\n {\n \"min\": -1,\n \"max\": -0.3\n },\n {\n \"min\": 0.3,\n \"max\": 1\n }\n ],\n \"values\": []\n },\n \"reporting_entities\": [\n \"228D42\"\n ],\n \"reporting_periods\": [\n {\n \"fiscal_year\": 2024,\n \"fiscal_quarter\": 3\n }\n ],\n \"authors\": {\n \"type\": \"person\",\n \"values\": [\n \"4L0FDS\"\n ]\n },\n \"speakers\": {\n \"type\": \"company\",\n \"values\": [\n \"DF67D7\"\n ]\n }\n },\n \"ranking_params\": {\n \"source_boost\": 1,\n \"freshness_boost\": 1\n },\n \"auto_enrich_filters\": true\n },\n \"search_mode\": \"fast\"\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"entity_id": "228D42",
"documents": [
{
"id": "57BB2AD919....",
"headline": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call",
"chunks": [
{
"cnum": 7,
"text": "Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below.\nMSFT Price Action: Microsoft stock is up 5.5% to $417.17 year-over-year in after-hours trading Wednesday versus a 52-week trading range of $344.79 to $468.35.",
"relevance": 0.8949412447701082,
"rerank_relevance": 0.6432
}
],
"timestamp": "2025-04-30T21:30:00Z",
"url": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack"
}
]
}
],
"usage": {
"api_query_units": 0.7
},
"metadata": {
"request_id": "user_2k3Z4SerTUIieyCfQhGR5UF2Af3",
"timestamp": "2025-09-12T11:10:46.019077+00:00"
}
}Authorizations
Body
application/json
Entities to group the results by. Each item is a set of entity ids searched with the same scope. Duplicate ids across items are merged.
Minimum array length:
1Show child attributes
Show child attributes
The search run for every entity in the watchlist. Unlike /v1/search, max_chunks, texts and external_search are not accepted inside query.
Show child attributes
Show child attributes
Search mode. Only fast is available for watchlist search.
Available options:
fast How many chunks to return and how to distribute them across the watchlist. When omitted, 100 chunks in total are spread across the entities.
Show child attributes
Show child attributes
Response
200 - application/json
Search results grouped per watchlist entity
One group per requested entity, in request order. Entities without matches have an empty documents array.
Show child attributes
Show child attributes
API usage for the request. Shape depends on the account consumption model.
- Query Units
- Tokens
Show child attributes
Show child attributes
Request metadata and timing information.
Show child attributes
Show child attributes
Was this page helpful?