---
title: "Search documents"
method: POST
path: "/v1/search"
tags: ["Search"]
---

# Search documents

`POST /v1/search`

Easily find the most relevant information from trusted sources and your own data. Use it to power agents that give accurate, real-time answers.

## Request body

- object
  - `search_mode` 'fast' | 'smart', required — **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)
  - `include_audit` boolean — 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` object, required
    - `text` string — Natural-language search string. It is not mandatory when filtering by entities, keywords, or tags with the filters below.
    - `filters` object
      - `timestamp` object — Temporal filter to retrieve documents with a timestamp within a start and end date.
        - `start` string, date-time — Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')
        - `end` string, date-time — End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')
      - `document_type` object — 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.
        - `mode` 'INCLUDE' | 'EXCLUDE', required — Filter mode for document type selection.
        - `values` union[], required — 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'.
          - union
            - object — Document type object with type and optional subtypes for more precise filtering.
              - …
            - 'NEWS' | 'TRANSCRIPT' | 'FILING' | 'TRANSCRIPT-PRESENTATION' | 'INVESTMENT-RESEARCH' — Deprecated: Use the object format with 'type' and optional 'subtypes' instead.
      - `source` object — Source filter to retrieve documents from specific sources.
        - `mode` 'INCLUDE' | 'EXCLUDE', required — Filter mode for source selection.
        - `values` string[], required — Array of source IDs to include or exclude based on the mode.
      - `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.
        - `mode` 'INCLUDE' | 'EXCLUDE', required — Filter mode for category selection.
        - `values` string[], required — Array of categories to include or exclude based on the mode.
      - `keyword` object — Keyword filter to retrieve chunks based on keyword presence.
        - `search_in` 'HEADLINE' | 'BODY' | '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.
        - `all_of` string[], required — Array of keywords that must all be present in the chunk.
        - `any_of` string[], required — Array of keywords where at least one must be present in the chunk.
        - `none_of` string[], required — Array of keywords that must not be present in the chunk.
      - `entity` object — Entity filter to retrieve chunks where entities were identified.
        - `search_in` 'HEADLINE' | 'BODY' | '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.
        - `all_of` string[], required — Array of entity IDs that must all be present in the chunk.
        - `any_of` string[], required — Array of entity IDs where at least one must be present in the chunk.
        - `none_of` string[], required — Array of entity IDs that must not be present in the document.
      - `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.
        - `ranges` object[] — Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.
          - `min` number, float, required — Minimum sentiment score for this range.
          - `max` number, float, required — Maximum sentiment score for this range.
        - `values` string[] — Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering.
      - `reporting_entities` string[] — Select one or multiple companies for which the returned documents must have been reported by.
      - `reporting_periods` object[] — Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).
        - `fiscal_year` integer, required — Fiscal year
        - `fiscal_quarter` integer, required — Fiscal quarter (1-4)
      - `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.
        - `search_in` 'HEADLINE' | 'BODY' | '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.
        - `all_of` string[], required — Array of topics that must all be present in the chunk.
        - `any_of` string[], required — Array of topics where at least one must be present in the chunk.
        - `none_of` string[], required — Array of topics that must not be present in the chunk.
      - `authors` object — Filter by document author. Useful for investment research.
        - `type` 'company' | 'person' | 'position', required — `person` for individuals, `company` for firms, or `position` for roles.
        - `values` string[], required — Entity IDs to filter by.
      - `speakers` object — Filter by speaker. Useful for transcripts and expert interviews.
        - `type` 'company' | 'person' | 'position', required — `person` for individuals, `company` for firms, or `position` for roles.
        - `values` string[], required — Entity IDs to filter by.
      - `tag` object — Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.
        - `any_of` string[], required — Array of tags where at least one must be present in the uploaded file.
      - `document` object — 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.
        - `mode` 'INCLUDE' | 'EXCLUDE', required — Filter mode for document selection.
        - `values` string[], required — Array of document IDs to include or exclude based on the mode.
      - `chunk` object — 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.
        - `from` integer, required — 1-based index of the first chunk to include in the search range.
        - `to` integer, required — 1-based index of the last chunk to include in the search range (inclusive).
    - `external_search` object — 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.
      - `mode` 'INCLUDE' | 'ONLY', required — `INCLUDE` returns Bigdata.com content plus external results. `ONLY` returns external results exclusively.
      - `values` string[] — Which external sources to search. Available: `web`. `social` coming soon.
    - `ranking_params` object — Groups parameters that affect the ranking algorithm and determine chunk relevance.
      - `content_diversification` object — Prevents single-source bias and semantically redundant content.
        - `enabled` boolean — If set to `true`, results are balanced across a wider range of providers and distinct viewpoints. Default: `true`.
      - `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.
      - `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.
      - `reranker` object — Applies a second ranking phase to improve precision. A cross-encoder model re-ranks the top candidates using the input query.
        - `enabled` boolean, required — Enable the re-ranker. True by default.
        - `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.
    - `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.
    - `auto_enrich_filters` boolean — 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.

## Response `200`

Search results

- object
  - `results` object[], required — Array of documents with one or more text chunks that match the query criteria.
    - `id` string, required — Unique document identifier, a 32-character hexadecimal string.
    - `headline` string, required — Document title.
    - `timestamp` string, date-time, required — Document timestamp in ANSI format and UTC timezone.
    - `document_type` string — It describes the type of document. (Values will change in future releases)
    - `source` object, required — Details about the source that published the document.
      - `id` string, required — RavenPack internal ID in the Knowledge Graph.
      - `name` string, required — Source name.
      - `rank` integer, required — Source ranking. Check Find Sources for more details.
    - `url` string, required — URL of the document.
    - `chunks` object[], required — Array of text chunks from the document.
      - `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.
      - `text` string, required — The text of the chunk.
      - `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.
      - `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.
      - `detections` object[], required — Array of entities detected in the chunk text.
        - `id` string, required — Unique identifier for the detected entity.
        - `start` integer, required — Start position of the entity in the chunk text.
        - `end` integer, required — End position of the entity in the chunk text.
        - `type` string, required — Type of the detected entity (e.g., 'entity', 'topic').
      - `text_locations` object[] — Coordinates to locate each chunk inside the document.
        - `paragraph_num` integer, required — The paragraph number.
        - `sentence_num` integer, required — The sentence number.
  - `external_results` object — External search results grouped by source (e.g. `web`).
  - `metadata` object — Request metadata and timing information.
    - `request_id` string, required — Unique identifier for the request.
    - `timestamp` string, date-time, required — Timestamp when the response was generated.
    - `audit` object — Detailed breakdown of the resolved queries that were executed. Only present when `include_audit` is set to true in the request.
      - `queries` object[] — Array of resolved queries that were executed by the system.
        - `auto_enrich_filters` boolean — Whether automatic filter enrichment was applied to this query.
        - `filters` object — The resolved filters that were used for this query.
          - `document_type` object — Resolved document type filter.
            - `mode` 'INCLUDE' | 'EXCLUDE' — Filter mode for document type selection.
            - `values` object[] — Array of resolved document type objects.
              - …
          - `reporting_entities` string[] — Resolved reporting entity IDs.
          - `reporting_periods` object[] — Resolved reporting periods.
            - `fiscal_year` integer — Fiscal year.
            - `fiscal_quarter` integer — Fiscal quarter (1-4).
        - `max_chunks` integer — Maximum number of chunks for this query.
        - `ranking_params` object — Ranking parameters used for this query.
          - `source_boost` number, float — Source boost value applied.
          - `freshness_boost` number, float — Freshness boost value applied.
          - `reranker` object — Reranker configuration used.
            - `enabled` boolean — Whether the reranker was enabled.
  - `usage` union, required — API usage for the request. Shape depends on the account consumption model.
    - QuotaUsageUnits — Usage under the query-units consumption model.
      - `api_query_units` number, float, required — Number of API query units consumed by this request.
    - QuotaUsageTokens — Token usage for the request, keyed by content tier.

---

[API](https://skmtc.dev/bigdata/apis/bigdata-structured-data-api.md) · [All operations](https://skmtc.dev/bigdata/apis/bigdata-structured-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bigdata/bigdata-structured-data-api/revisions/18082de268c4/schema)