--- title: "Connected Topics" method: POST path: "/v1/search/co-mentions/topics" tags: ["Co-mentions"] --- # Connected Topics `POST /v1/search/co-mentions/topics` Explore topics associated with your search filters to reveal deeper connections. This endpoint retrieves the top N topics ranked by chunk volume and headline volume, merges the two sets, and returns topics with combined or individual counts. ## Request body - object - `query` object, required - `text` string — Natural-language search string. It is not mandatory when filtering by entities or keywords 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. - `limit` integer — Maximum number of topics to retrieve. It must be lower than or equal to 1000. ## Response `200` Topics co-mentions results - object - `results` object, required — Object containing array of topics that are co-mentioned with the search query. - `topics` object[], required — Array of topics co-mentioned with the search query. - `id` string, required — Unique topic identifier. - `total_chunks_count` integer, required — Total number of chunks where this topic appears. - `total_headlines_count` integer, required — Total number of titles where this topic appears. - `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)