--- title: "Search volume" method: POST path: "/v1/search/volume" tags: ["Search"] --- # Search volume `POST /v1/search/volume` Get document and chunk volume statistics over time for a search query, aggregated by date with sentiment analysis. ## Request body - object - `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. - `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). - `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` Volume search results - object - `results` object, required — Volume statistics aggregated by date and totals. - `volume` object[], required — Array of volume statistics for each date in the time range. - `date` string, date, required — Date in YYYY-MM-DD format. - `documents` integer, required — Number of documents matching the query on this date. - `chunks` integer, required — Number of chunks matching the query on this date. - `sentiment` number, float — Average sentiment score for chunks on this date, ranging from -1.00 to 1.00. - `total` object, required — Aggregated totals across all dates in the time range. - `documents` integer, required — Total number of documents matching the query. - `chunks` integer, required — Total number of chunks matching the query. - `sentiment` number, float — Average sentiment score across all chunks, ranging from -1.00 to 1.00. - `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. - `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. - QuotaUsageTokenCount — Token usage for the request. - `tokens` integer, required — Total number of tokens consumed by this request. --- [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)