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
Search an entire watchlist and get results grouped by entity.
Unlike /v1/search, where a few entities can dominate the results, watchlist search distributes results more evenly across your watchlist. You can choose how chunks are allocated:
max_chunks.per_entity: false– split a total chunk budget across all entities.max_chunks.per_entity: true– return up to a fixed number of chunks for each entity.
The response contains one group for every requested entity, in the same order as the request.
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.
Show child attributes
Show child attributes
The search run for every entity in the watchlist. Provide at least one of text or filters.
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?