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.

POST /v1/search

Try it

Search documents

cURL

curl --request POST \
  --url https://api.bigdata.com/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "query": {
    "text": "Microsoft earnings call highlights",
    "filters": {
      "timestamp": {
        "start": "2025-01-01T14:15:22Z",
        "end": "2025-08-11T14:15:22Z"
      },
      "topic": {
        "any_of": [
          "business,partnerships,partnership"
        ]
      },
      "document_type": {
        "mode": "INCLUDE",
        "values": [
          "NEWS"
        ]
      },
      "entity": {
        "all_of": [],
        "any_of": [
          "81660B",
          "C379FA",
          "94A3FB"
        ],
        "none_of": []
      },
      "tag": {
        "any_of": [
          "research-report",
          "any-tag"
        ]
      },
      "category": {
        "mode": "INCLUDE",
        "values": [
          "expert_interviews",
          "news",
          "research"
        ]
      }
    },
    "ranking_params": {
      "source_boost": 10,
      "freshness_boost": 1,
      "reranker": {
        "enabled": false,
        "threshold": 0.8
      }
    },
    "max_chunks": 100
  }
}
'

200

{
  "results": [
    {
      "id": "57BB2AD919....",
      "headline": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call",
      "timestamp": "2025-04-30T21:30:00Z",
      "source": {
        "id": "D4B903",
        "name": "Factset Transcripts",
        "rank": "RANK_1"
      },
      "url": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack",
      "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,
          "sentiment": 0.33,
          "detections": [
            {
              "id": "ACE54B",
              "start": 23,
              "end": 38,
              "type": "entity"
            }
          ]
        }
      ],
      "document_type": "Earnings Call"
    }
  ],
  "metadata": {
    "request_id": "user_2k3Z4SerTUIieyCfQhGR5UF2Af3",
    "timestamp": "2025-09-12T11:10:46.019077+00:00"
  },
  "usage": {
    "api_query_units": 0.7
  }
}

Authorizations

X-API-KEY · string · header · required

Body

application/json

query · object · required

Show child attributes

query. text · string

Natural-language search string. It is not mandatory when filtering by entities, keywords, or tags with the filters below.

Example:

"Microsoft earnings call highlights"

query. filters · object

Show child attributes

query.filters. timestamp · object

Temporal filter to retrieve documents with a timestamp within a start and end date.

Show child attributes

query.filters.timestamp. start · string<date-time>

Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')

query.filters.timestamp. end · string<date-time>

End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')

query.filters. document_type · object

Document type filter to retrieve documents of specific types.

Show child attributes

query.filters.document_type. mode · enum<string> · required

Filter mode for document type selection.

Available options: INCLUDE, EXCLUDE

Example:

"INCLUDE"

query.filters.document_type. values · enum<string>[] · required

Array of document types to include or exclude based on the mode.

Available options: NEWS, TRANSCRIPT, FILING, TRANSCRIPT-PRESENTATION

Example:

["NEWS"]

query.filters. source · object

Source filter to retrieve documents from specific sources.

Show child attributes

query.filters.source. mode · enum<string> · required

Filter mode for source selection.

Available options: INCLUDE, EXCLUDE

Example:

"INCLUDE"

query.filters.source. values · string[] · required

Array of source IDs to include or exclude based on the mode.

Example:

["ED68DC"]

query.filters. category · object

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.

Show child attributes

query.filters.category. mode · enum<string> · required

Filter mode for category selection.

Available options: INCLUDE, EXCLUDE

Example:

"INCLUDE"

query.filters.category. values · enum<string>[] · required

Array of categories to include or exclude based on the mode.

Available options: expert_interviews, filings, my_files, news, podcasts, research, transcripts

Example:

["expert_interviews", "news", "research"]

query.filters. keyword · object

Keyword filter to retrieve chunks based on keyword presence.

Show child attributes

query.filters.keyword. all_of · string[] · required

Array of keywords that must all be present in the chunk.

Example:

[]

query.filters.keyword. any_of · string[] · required

Array of keywords where at least one must be present in the chunk.

Example:

[]

query.filters.keyword. none_of · string[] · required

Array of keywords that must not be present in the chunk.

Example:

["operating"]

query.filters.keyword. search_in · enum<string> · default: ALL

Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided.

Available options: HEADLINE, BODY, ALL

Example:

"HEADLINE"

query.filters. entity · object

Entity filter to retrieve chunks where entities were identified.

Show child attributes

query.filters.entity. all_of · string[] · required

Array of entity IDs that must all be present in the chunk.

Example:

[]

query.filters.entity. any_of · string[] · required

Array of entity IDs where at least one must be present in the chunk.

Example:

["228D42"]

query.filters.entity. none_of · string[] · required

Array of entity IDs that must not be present in the document.

Example:

[]

query.filters.entity. search_in · enum<string> · default: ALL

Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided.

Available options: HEADLINE, BODY, ALL

Example:

"HEADLINE"

query.filters. sentiment · object

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.

Show child attributes

query.filters.sentiment. ranges · object[]

Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.

Show child attributes

query.filters.sentiment.ranges. min · number<float> · required

Minimum sentiment score for this range.

Required range: -1 <= x <= 1

Example:

-1

query.filters.sentiment.ranges. max · number<float> · required

Maximum sentiment score for this range.

Required range: -1 <= x <= 1

Example:

-0.3

Example:

[
  { "min": -1, "max": -0.3 },
  { "min": 0.3, "max": 1 }
]

query.filters.sentiment. values · enum<string>[] · deprecated

Array of sentiment categories to filter by. Sunsetting: Use ranges instead for more precise sentiment filtering.

Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1)

Available options: positive, negative, neutral

Example:

["positive", "negative", "neutral"]

query.filters. reporting_entities · string[]

Select one or multiple companies for which the returned documents must have been reported by.

Example:

["228D42"]

query.filters. reporting_periods · object[]

Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).

Show child attributes

query.filters.reporting_periods. fiscal_year · integer · required

Fiscal year

Example:

2024

query.filters.reporting_periods. fiscal_quarter · integer · required

Fiscal quarter (1-4)

Required range: 1 <= x <= 4

Example:

3

Example:

[
  { "fiscal_year": 2024, "fiscal_quarter": 3 }
]

query.filters. topic · object

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.

Show child attributes

query.filters.topic. all_of · string[] · required

Array of topics that must all be present in the chunk.

Example:

[]

query.filters.topic. any_of · string[] · required

Array of topics where at least one must be present in the chunk.

Example:

[
  "business,stock-prices,stock-price-volatility,down,"
]

query.filters.topic. none_of · string[] · required

Array of topics that must not be present in the chunk.

Example:

[]

query.filters.topic. search_in · enum<string> · default: ALL

Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided.

Available options: HEADLINE, BODY, ALL

Example:

"HEADLINE"

query.filters. tag · object

Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.

Show child attributes

query.filters.tag. any_of · string[] · required

Array of tags where at least one must be present in the uploaded file.

Example:

["research-report", "any-tag"]

query. ranking_params · object

Groups parameters that affect the ranking algorithm and determine chunk relevance.

Show child attributes

query.ranking_params. source_boost · number<float>

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.

Required range: 0 <= x <= 10

Example:

1

query.ranking_params. freshness_boost · number<float>

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.

Required range: 0 <= x <= 10

Example:

1

query.ranking_params. reranker · object

Applies a second ranking phase to improve precision. A cross-encoder model re-ranks the top candidates using the input query.

Show child attributes

query.ranking_params.reranker. enabled · boolean · default: true · required

Enable the re-ranker. True by default.

Example:

true

query.ranking_params.reranker. threshold · number<float>

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.

Required range: 0 <= x <= 1

Example:

0.8

query. max_chunks · integer

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

Response

200 - application/json

Search results

results · object[] · required

Array of documents with one or more text chunks that match the query criteria.

Show child attributes

results. id · string · required

Unique document identifier, a 32-character hexadecimal string.

Example:

"57BB2AD919...."

results. headline · string · required

Document title.

Example:

"Headline example: Microsoft Corp.: Q3 2025 Earnings Call"

results. timestamp · string<date-time> · required

Document timestamp in ANSI format and UTC timezone.

Example:

"2025-04-30T21:30:00Z"

results. source · object · required

Details about the source that published the document.

Show child attributes

results.source. id · string · required

RavenPack internal ID in the Knowledge Graph.

Example:

"D4B903"

results.source. name · string · required

Source name.

Example:

"Factset Transcripts"

results.source. rank · integer · required

Source ranking. Check Find Sources for more details.

Example:

"RANK_1"

results. url · string · required

URL of the document.

Example:

"https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack"

results. chunks · object[] · required

Array of text chunks from the document.

Show child attributes

results.chunks. cnum · integer · required

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

results.chunks. text · string · required

The text of the chunk.

Example:

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

results.chunks. relevance · number<float> · required

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

results.chunks. sentiment · number<float> · required

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

results.chunks. detections · object[] · required

Array of entities detected in the chunk text.

Show child attributes

results.chunks.detections. id · string · required

Unique identifier for the detected entity.

Example:

"ACE54B"

results.chunks.detections. start · integer · required

Start position of the entity in the chunk text.

Example:

23

results.chunks.detections. end · integer · required

End position of the entity in the chunk text.

Example:

38

results.chunks.detections. type · string · required

Type of the detected entity (e.g., 'entity', 'topic').

Example:

"entity"

results. document_type · string

It describes the type of document. (Values will change in future releases)

Example:

"Earnings Call"

metadata · object

Request metadata and timing information.

Show child attributes

metadata. request_id · string · required

Unique identifier for the request.

Example:

"user_2k3Z4SerTUIieyCfQhGR5UF2Af3"

metadata. timestamp · string<date-time> · required

Timestamp when the response was generated.

Example:

"2025-09-12T11:10:46.019077+00:00"

usage · object

API usage information for the request.

Show child attributes

usage. api_query_units · number<float> · required

Number of API query units consumed by this request.

Example:

0.7