> ## 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 documents
> Easily find the most relevant information from trusted sources and your own data. Use it to power agents that give accurate, real-time answers.
**NEW! External Search**
Retrieve live web results—company pages, technical sources, niche publications—alongside Bigdata.com's premium financial content. Use `external_search` with mode `INCLUDE` to combine both, or `ONLY` to search just the web
[Read the announcement →](/blog/search/introducing-web-search)
## OpenAPI
````yaml /api-rest/openapi/openapi_search_service.json post /v1/search
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:
post:
tags:
- Search
summary: Search documents
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.
**NEW! External Search**
Retrieve live web results—company pages, technical sources, niche
publications—alongside Bigdata.com's premium financial content. Use
`external_search` with mode `INCLUDE` to combine both, or `ONLY` to
search just the web
[Read the announcement →](/blog/search/introducing-web-search)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
search_mode:
type: string
description: >-
**fast** (default): Runs a single query using the specified
filters. Best for pre-processed queries where you control
the filters.
**smart**: Analyzes the query text to automatically define
search filters and runs multiple sub-queries to ensure
better coverage. Ideal for sending user questions directly
without pre-processing. When using smart mode, only
`timestamp` and `source` filters are allowed; using any
other filters will result in a 400 Bad Request error.
Click [here for a more detailed
comparison](/getting-started/bigdata_api_pricing#what-is-the-difference-between-fast-and-smart-search-modes)
enum:
- fast
- smart
include_audit:
type: boolean
description: >-
When set to true, the response metadata will include an
`audit` object containing the resolved queries that were
actually executed. Useful for debugging and understanding
how the system interpreted your request.
query:
type: object
properties:
text:
type: string
description: >-
Natural-language search string.
It is not mandatory when filtering by entities,
keywords, or tags with the filters below.
example: Microsoft earnings call highlights
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.
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
- 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
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
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
external_search:
type: object
description: >-
Add external sources (e.g. live web) to your search. Use
`INCLUDE` to get both Bigdata.com content and external
results, or `ONLY` to search external sources
exclusively. Results appear in `external_results`
grouped by source.
For external search, only `query.text` is used; any
other query parameters apply only to Bigdata content.
In Fast mode, external search is always called when
enabled. In Smart mode, only `INCLUDE` mode is
supported—the system decides whether external search is
needed based on query intent. If not called, no
additional cost is incurred.
**Note:** Not available in Batch Search.
properties:
mode:
type: string
description: >-
`INCLUDE` returns Bigdata.com content plus external
results. `ONLY` returns external results
exclusively.
enum:
- INCLUDE
- ONLY
values:
type: array
description: >-
Which external sources to search. Available: `web`.
`social_X` (Twitter) coming soon.
items:
type: string
enum:
- web
minItems: 1
required:
- mode
ranking_params:
type: object
description: >-
Groups parameters that affect the ranking algorithm and
determine chunk relevance.
properties:
content_diversification:
type: object
description: >-
Prevents single-source bias and semantically
redundant content.
properties:
enabled:
type: boolean
description: >-
If set to `true`, results are balanced across a
wider range of providers and distinct
viewpoints. Default: `true`.
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
required:
- enabled
max_chunks:
type: integer
description: >-
Maximum number of chunks to retrieve. It must be lower
than or equal to 1000.
The response might contain a lower number of chunks due
to discarding duplicated chunks after the matching
phase.
example: 10
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.
required:
- search_mode
- query
example:
search_mode: fast
query:
text: Type a question to retrieve documents chunks
responses:
'200':
description: Search results
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: >-
Array of documents with one or more text chunks that match
the query criteria.
items:
type: object
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'
document_type:
type: string
description: >-
It describes the type of document. (Values will
change in future releases)
example: Earnings Call
source:
type: object
description: >-
Details about the source that published the
document.
properties:
id:
type: string
description: RavenPack internal ID in the Knowledge Graph.
example: D4B903
name:
type: string
description: Source name.
example: Factset Transcripts
rank:
type: integer
description: >-
Source ranking. Check Find Sources for more
details.
example: RANK_1
required:
- id
- name
- rank
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: Array of text chunks from the document.
items:
type: object
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
sentiment:
type: number
format: float
description: >-
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.
example: 0.33
detections:
type: array
description: Array of entities detected in the chunk text.
items:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the detected
entity.
example: ACE54B
start:
type: integer
description: >-
Start position of the entity in the
chunk text.
example: 23
end:
type: integer
description: >-
End position of the entity in the chunk
text.
example: 38
type:
type: string
description: >-
Type of the detected entity (e.g.,
'entity', 'topic').
example: entity
required:
- id
- start
- end
- type
text_locations:
type: array
description: >-
Coordinates to locate each chunk inside the
document.
items:
type: object
properties:
paragraph_num:
type: integer
description: The paragraph number.
example: 1
sentence_num:
type: integer
description: The sentence number.
example: 1
required:
- paragraph_num
- sentence_num
required:
- cnum
- text
- relevance
- sentiment
- detections
required:
- id
- headline
- timestamp
- source
- url
- chunks
external_results:
type: object
description: External search results grouped by source (e.g. `web`).
additionalProperties:
type: array
items:
$ref: '#/components/schemas/ExternalWebResult'
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'
audit:
type: object
description: >-
Detailed breakdown of the resolved queries that were
executed. Only present when `include_audit` is set to
true in the request.
properties:
queries:
type: array
description: >-
Array of resolved queries that were executed by
the system.
items:
type: object
properties:
auto_enrich_filters:
type: boolean
description: >-
Whether automatic filter enrichment was
applied to this query.
filters:
type: object
description: >-
The resolved filters that were used for this
query.
properties:
document_type:
type: object
description: Resolved document type filter.
properties:
mode:
type: string
description: Filter mode for document type selection.
enum:
- INCLUDE
- EXCLUDE
values:
type: array
description: Array of resolved document type objects.
items:
type: object
properties:
type:
type: string
description: The document type.
example: TRANSCRIPT
subtypes:
type: array
description: Array of document subtypes.
items:
type: string
example:
- EARNINGS_CALL
reporting_entities:
type: array
description: Resolved reporting entity IDs.
items:
type: string
example:
- BA9E0C
reporting_periods:
type: array
description: Resolved reporting periods.
items:
type: object
properties:
fiscal_year:
type: integer
description: Fiscal year.
example: 2025
fiscal_quarter:
type: integer
description: Fiscal quarter (1-4).
example: 4
max_chunks:
type: integer
description: Maximum number of chunks for this query.
example: 100
ranking_params:
type: object
description: Ranking parameters used for this query.
properties:
source_boost:
type: number
format: float
description: Source boost value applied.
example: 1
freshness_boost:
type: number
format: float
description: Freshness boost value applied.
example: 1
reranker:
type: object
description: Reranker configuration used.
properties:
enabled:
type: boolean
description: Whether the reranker was enabled.
example: true
required:
- request_id
- timestamp
usage:
type: object
description: API usage information for the request.
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
required:
- results
components:
schemas:
ExternalWebResult:
type: object
description: One external document-style hit (e.g. from web search).
properties:
headline:
type: string
description: Title of the external page or snippet.
timestamp:
type: string
format: date-time
nullable: true
description: Publication or retrieval-related timestamp when available.
chunks:
type: array
description: Text chunks for this external hit.
items:
$ref: '#/components/schemas/ExternalWebChunk'
src_name:
type: string
description: Display name of the web or external source.
url:
type: string
format: uri
nullable: true
description: URL of the external result, when available.
required:
- headline
- chunks
- src_name
ExternalWebChunk:
type: object
description: A text chunk from an external (e.g. web) search result.
properties:
cnum:
type: integer
description: Chunk index within the external result (1-based ordering).
example: 1
text:
type: string
description: Chunk text content.
relevance:
type: number
format: float
description: Relevance score between 0 and 1.
example: 0.85
rerank_relevance:
type: number
format: float
nullable: true
description: Score after reranking, if applicable.
required:
- cnum
- text
- relevance
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````