> ## 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. # 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`. ## OpenAPI ````yaml /api-rest/openapi/openapi_search_service.json post /v1/search/watchlist openapi: 3.0.3 info: title: Bigdata Search API version: 1.0.0 description: >- Easily find the most relevant information from trusted sources and your own data. Use it to power agents that give accurate, real-time answers. servers: - url: https://api.bigdata.com/ security: - ApiKeyAuth: [] paths: /v1/search/watchlist: post: tags: - Search summary: Search watchlist description: >- 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`. operationId: search_watchlist requestBody: required: true content: application/json: schema: type: object required: - watchlists - query properties: search_mode: type: string enum: - fast default: fast description: Search mode. Only `fast` is available for watchlist search. watchlists: type: array minItems: 1 description: >- 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. items: type: object required: - entities properties: entities: type: array minItems: 1 description: >- Entity identifiers from the Knowledge Graph (alphanumeric, at most 64 characters). Use the Knowledge Graph endpoints to resolve companies, people, places and other entities to their ids. items: type: string pattern: ^[A-Za-z0-9]+$ maxLength: 64 example: - 228D42 - D8442A scope: type: string enum: - all - headline - body default: all description: >- Where an entity must be detected for a chunk to count for it: anywhere in the document (`all`), in the headline (`headline`) or in the chunk text (`body`). max_chunks: type: object required: - value description: >- How many chunks to return and how to distribute them across the watchlist. When omitted, 100 chunks in total are spread across the entities. properties: value: type: integer minimum: 1 example: 5 description: >- Number of chunks. With `per_entity: false` it is the total across all entities: up to 512 while the reranker is enabled (the default), up to 1000 with `ranking_params.reranker.enabled: false`. With `per_entity: true` it applies to every entity (1-100), and `entities × value` must not exceed 4000. per_entity: type: boolean default: false description: >- `false`: `value` is a total budget shared by the watchlist, allocated to the entities with the most relevant matches. `true`: up to `value` chunks are returned for every entity. query: type: object required: - text description: >- The search run for every entity in the watchlist. Unlike `/v1/search`, `max_chunks`, `texts` and `external_search` are not accepted inside `query`. properties: text: type: string minLength: 4 maxLength: 1400 description: >- Natural-language search string, run for every entity in the watchlist. example: supply chain disruptions filters: type: object properties: timestamp: type: object description: >- Temporal filter to retrieve documents with a timestamp within a start and end date. properties: start: type: string format: date-time description: >- Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z') end: type: string format: date-time description: >- End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z') document_type: type: object description: >- Document type filter to retrieve documents of specific types. Values can be either plain strings (deprecated) or objects with 'type' and optional 'subtypes' for more precise filtering. properties: mode: type: string description: Filter mode for document type selection. enum: - INCLUDE - EXCLUDE values: type: array description: >- Array of document type values to include or exclude based on the mode. Each value can be a string (deprecated) or an object with 'type' and optional 'subtypes'. items: oneOf: - type: object description: >- Document type object with type and optional subtypes for more precise filtering. properties: type: type: string enum: - NEWS - TRANSCRIPT - FILING - TRANSCRIPT-PRESENTATION - INVESTMENT-RESEARCH description: The document type. subtypes: type: array description: >- Optional array of subtypes for more specific filtering. Supported subtypes vary by type: For [FILING](/getting-started/search/query_filters#filing): SEC_10_K, SEC_10_Q, SEC_8_K, SEC_20_F, SEC_S_1, SEC_S_3, SEC_6_K, SEC_DEF_14A, SEC_485APOS, SEC_485BPOS, SEC_497, SEC_497AD, SEC_497J, SEC_497K, SEC_497VPI, SEC_497VPSUB, SEC_497VPU, SEC_N_CSR, SEC_N_CSR_A, SEC_N_CSRS, SEC_N_CSRS_A, SEC_NPORT_P_A, SEC_NT_NCSR, SEC_NT_NCSR_A, SEC_NT_NPORT_P, SEC_NTFNCSR. For [TRANSCRIPT and TRANSCRIPT-PRESENTATION](/getting-started/search/query_filters#transcript): ANALYST_INVESTOR_SHAREHOLDER_MEETING, CONFERENCE_CALL, GENERAL_PRESENTATION, EARNINGS_CALL, EARNINGS_RELEASE, GUIDANCE_CALL, SALES_REVENUE_CALL, SALES_REVENUE_RELEASE, SPECIAL_SITUATION_MA, SHAREHOLDERS_MEETING, MANAGEMENT_PLAN_ANNOUNCEMENT, INVESTOR_CONFERENCE_CALL. For [INVESTMENT-RESEARCH](/getting-started/search/query_filters#investment-research): COMPANY_REPORT, COVERAGE_ANALYSIS, ECONOMIC_REPORT, FIXED_INCOME_REPORT, FUND_REPORT, FX_AND_DERIVATIVES_REPORT, GENERIC_REPORT, INDEX_REPORT, INDUSTRY_REPORT, MARKET_UPDATE, PORTFOLIO_STRATEGY, PORTFOLIO_SUMMARY, RATING_REPORT, RESEARCH_NOTE, THEMATIC_ANALYSIS. items: type: string enum: - SEC_10_K - SEC_10_Q - SEC_8_K - SEC_20_F - SEC_S_1 - SEC_S_3 - SEC_6_K - SEC_DEF_14A - SEC_485APOS - SEC_485BPOS - SEC_497 - SEC_497AD - SEC_497J - SEC_497K - SEC_497VPI - SEC_497VPSUB - SEC_497VPU - SEC_N_CSR - SEC_N_CSR_A - SEC_N_CSRS - SEC_N_CSRS_A - SEC_NPORT_P_A - SEC_NT_NCSR - SEC_NT_NCSR_A - SEC_NT_NPORT_P - SEC_NTFNCSR - ANALYST_INVESTOR_SHAREHOLDER_MEETING - CONFERENCE_CALL - GENERAL_PRESENTATION - EARNINGS_CALL - EARNINGS_RELEASE - GUIDANCE_CALL - SALES_REVENUE_CALL - SALES_REVENUE_RELEASE - SPECIAL_SITUATION_MA - SHAREHOLDERS_MEETING - MANAGEMENT_PLAN_ANNOUNCEMENT - INVESTOR_CONFERENCE_CALL - COMPANY_REPORT - COVERAGE_ANALYSIS - ECONOMIC_REPORT - FIXED_INCOME_REPORT - FUND_REPORT - FX_AND_DERIVATIVES_REPORT - GENERIC_REPORT - INDEX_REPORT - INDUSTRY_REPORT - MARKET_UPDATE - PORTFOLIO_STRATEGY - RATING_REPORT - RESEARCH_NOTE - THEMATIC_ANALYSIS - PORTFOLIO_SUMMARY required: - type - type: string enum: - NEWS - TRANSCRIPT - FILING - TRANSCRIPT-PRESENTATION - INVESTMENT-RESEARCH deprecated: true description: >- Deprecated: Use the object format with 'type' and optional 'subtypes' instead. required: - mode - values source: type: object description: >- Source filter to retrieve documents from specific sources. properties: mode: type: string description: Filter mode for source selection. enum: - INCLUDE - EXCLUDE values: type: array description: >- Array of source IDs to include or exclude based on the mode. items: type: string example: - ED68DC required: - mode - values category: type: object description: >- Category filter to retrieve documents from specific categories. This enables selecting a related set of sources without having to add a long list of source IDs. properties: mode: type: string description: Filter mode for category selection. enum: - INCLUDE - EXCLUDE values: type: array description: >- Array of categories to include or exclude based on the mode. items: type: string enum: - expert_interviews - filings - my_files - news - news_premium - news_public - podcasts - research - research_academic_journals - research_investment_research - transcripts required: - mode - values tier: type: object description: >- Content tier filter to retrieve documents from specific content tiers. Tiers are how content is packaged and priced under the token-based consumption model. properties: mode: type: string description: Filter mode for content tier selection. enum: - INCLUDE - EXCLUDE values: type: array description: >- Array of content tiers to include or exclude based on the mode. items: type: string enum: - corporate-communications - premium-news - expert-interviews - earnings-transcripts - regulatory-filings - podcasts - web - private-data required: - mode - values keyword: type: object description: >- Keyword filter to retrieve chunks based on keyword presence. properties: search_in: type: string enum: - HEADLINE - BODY - ALL description: >- Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided. all_of: type: array description: >- Array of keywords that must all be present in the chunk. items: type: string example: [] any_of: type: array description: >- Array of keywords where at least one must be present in the chunk. items: type: string example: [] none_of: type: array description: >- Array of keywords that must not be present in the chunk. items: type: string example: - operating required: - all_of - any_of - none_of entity: type: object description: >- Entity filter to retrieve chunks where entities were identified. properties: search_in: type: string enum: - HEADLINE - BODY - ALL description: >- Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided. all_of: type: array description: >- Array of entity IDs that must all be present in the chunk. items: type: string example: [] any_of: type: array description: >- Array of entity IDs where at least one must be present in the chunk. items: type: string example: - 228D42 none_of: type: array description: >- Array of entity IDs that must not be present in the document. items: type: string example: [] required: - all_of - any_of - none_of sentiment: type: object description: >- Sentiment filter to retrieve chunks based on sentiment score. All chunks contain a sentiment score ranging from -1.00 to 1.00, indicating how that chunk might impact the market and whether it will have a positive or negative effect. properties: ranges: type: array description: >- Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score. items: type: object properties: min: type: number format: float description: Minimum sentiment score for this range. minimum: -1 maximum: 1 example: -1 max: type: number format: float description: Maximum sentiment score for this range. minimum: -1 maximum: 1 example: -0.3 required: - min - max example: - min: -1 max: -0.3 - min: 0.3 max: 1 values: type: array description: >- Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering. deprecated: true items: type: string enum: - positive - negative - neutral description: >- Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1) reporting_entities: type: array description: >- Select one or multiple companies for which the returned documents must have been reported by. items: type: string example: - 228D42 reporting_periods: type: array description: >- Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023). items: type: object properties: fiscal_year: type: integer description: Fiscal year example: 2024 fiscal_quarter: type: integer description: Fiscal quarter (1-4) minimum: 1 maximum: 4 example: 3 required: - fiscal_year - fiscal_quarter example: - fiscal_year: 2024 fiscal_quarter: 3 topic: type: object description: >- Topic filter to retrieve chunks based on topic presence. Example: {"any_of": ["business,stock-prices,stock-price-volatility,down,"]} to find documents about stock price volatility. properties: search_in: type: string enum: - HEADLINE - BODY - ALL description: >- Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided. all_of: type: array description: >- Array of topics that must all be present in the chunk. items: type: string example: [] any_of: type: array description: >- Array of topics where at least one must be present in the chunk. items: type: string example: - >- business,stock-prices,stock-price-volatility,down, none_of: type: array description: >- Array of topics that must not be present in the chunk. items: type: string example: [] required: - all_of - any_of - none_of authors: type: object description: >- Filter by document author. Useful for investment research. properties: type: type: string enum: - company - person - position description: >- `person` for individuals, `company` for firms, or `position` for roles. values: type: array description: Entity IDs to filter by. items: type: string minItems: 1 required: - type - values example: type: person values: - 4L0FDS speakers: type: object description: >- Filter by speaker. Useful for transcripts and expert interviews. properties: type: type: string enum: - company - person - position description: >- `person` for individuals, `company` for firms, or `position` for roles. values: type: array description: Entity IDs to filter by. items: type: string minItems: 1 required: - type - values example: type: company values: - DF67D7 tag: type: object description: >- Tag filter to retrieve documents from uploaded files that have been tagged with specific tags. properties: any_of: type: array description: >- Array of tags where at least one must be present in the uploaded file. items: type: string example: - research-report - any-tag required: - any_of document: type: object description: >- Document filter to restrict the search to a list of specified documents. Use document IDs (e.g., from a previous search response) to search only within those documents. properties: mode: type: string description: Filter mode for document selection. enum: - INCLUDE - EXCLUDE values: type: array description: >- Array of document IDs to include or exclude based on the mode. items: type: string example: - 3C54E042B2B19B244F57D3C6415439D1 required: - mode - values chunk: type: object description: >- Chunk filter to narrow the search to a particular section within the document. Use when expanding the context of a previously retrieved chunk (e.g., from the 3rd chunk to the 7th). Useful to expand context around a chunk that was previously retrieved. Chunk indices are 1-based. properties: from: type: integer description: >- 1-based index of the first chunk to include in the search range. example: 3 to: type: integer description: >- 1-based index of the last chunk to include in the search range (inclusive). example: 7 required: - from - to ranking_params: type: object description: >- Groups parameters that affect the ranking algorithm and determine chunk relevance. Content diversification is always enabled for watchlist search and cannot be configured here. properties: source_boost: type: number format: float description: >- Controls how much the source rank influences relevance. Range: 0-10. Default: 1.0. 0 → source rank has no effect. 10 → maximum effect, boosting chunks from premium sources. minimum: 0 maximum: 10 example: 1 freshness_boost: type: number format: float description: >- Controls the influence of document timestamp on relevance. Range: 0-10. Default: 1.0. 0 → publishing time is ignored (useful for point-in-time research). 10 → most recent documents are heavily prioritized. minimum: 0 maximum: 10 example: 1 reranker: type: object description: >- Applies a second ranking phase to improve precision. A cross-encoder model re-ranks the top candidates using the input query. properties: enabled: type: boolean description: Enable the re-ranker. True by default. threshold: type: number format: float description: >- Reranker threshold to filter results by relevance score. Range: 0.0 to 1.0. The default reranker uses a threshold of 0.2, but you can set a custom threshold to improve precision and reduce noise. Higher values return fewer, more relevant results. minimum: 0 maximum: 1 example: 0.8 text: type: string description: >- Custom text for the cross-encoder to rank against. By default the reranker uses `query.text`. example: supply chain impact on manufacturing required: - enabled auto_enrich_filters: type: boolean description: >- Advanced parameter that controls automatic enrichment of filters using the query text. When set to true (default), the system automatically extracts and adds relevant filter values from the query text. Set to false when you have created a strict query with specific keywords and entity filters and you do not want any extra values added to those filters. responses: '200': description: Search results grouped per watchlist entity content: application/json: schema: type: object properties: results: type: array description: >- One group per requested entity, in request order. Entities without matches have an empty `documents` array. items: type: object required: - entity_id - documents properties: entity_id: type: string description: The watchlist entity identifier. example: 228D42 documents: type: array description: Documents whose chunks were assigned to this entity. items: type: object required: - id - headline - chunks properties: id: type: string description: >- Unique document identifier, a 32-character hexadecimal string. example: 57BB2AD919.... headline: type: string description: Document title. example: >- Headline example: Microsoft Corp.: Q3 2025 Earnings Call timestamp: type: string format: date-time description: >- Document timestamp in ANSI format and UTC timezone. example: '2025-04-30T21:30:00Z' url: type: string description: URL of the document. example: >- https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack chunks: type: array description: >- Chunks of this document assigned to the entity. A chunk is never returned under two entities. items: type: object required: - cnum - text - relevance properties: cnum: type: integer description: >- The index of the chunk in the document. You can use it to sort them in order. The first document chunk has cnum with the value 1. example: 7 text: type: string description: The text of the chunk. example: >- Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below. MSFT 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: type: number format: float description: >- A float between 0 and 1. Relevance indicates the degree to which a particular match aligns with the various terms in your query. It's important to note that the relevance scores you receive are only meaningful within the context of the same search. Each execution generates unique scores, so comparing relevance across different queries is not meaningful. example: 0.8949412447701082 rerank_relevance: type: number format: float nullable: true description: >- Cross-encoder relevance of the chunk for the query, between 0 and 1. Informational; `null` when the reranker did not score the chunk. example: 0.6432 usage: $ref: '#/components/schemas/SearchUsage' metadata: type: object description: Request metadata and timing information. properties: request_id: type: string description: Unique identifier for the request. example: user_2k3Z4SerTUIieyCfQhGR5UF2Af3 timestamp: type: string format: date-time description: Timestamp when the response was generated. example: '2025-09-12T11:10:46.019077+00:00' required: - request_id - timestamp components: schemas: SearchUsage: description: >- API usage for the request. Shape depends on the account consumption model. oneOf: - $ref: '#/components/schemas/QuotaUsageUnits' - $ref: '#/components/schemas/QuotaUsageTokens' QuotaUsageUnits: title: Query Units type: object description: Usage under the query-units consumption model. properties: api_query_units: type: number format: float description: Number of API query units consumed by this request. example: 0.7 required: - api_query_units QuotaUsageTokens: title: Tokens type: object description: Token usage for the request, keyed by content tier. additionalProperties: type: integer minimum: 0 example: premium_news_tokens: 300 regulatory_filings_tokens: 500 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````