> ## 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. # Connected Entities > Explore entities associated with your search filters to reveal deeper connections. This endpoint retrieves the top N entities ranked by chunk volume and headline volume, merges the two sets, and returns entities with combined or individual counts. ## OpenAPI ````yaml /api-rest/openapi/openapi_search_service.json post /v1/search/co-mentions/entities 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/co-mentions/entities: post: tags: - Co-mentions summary: Connected Entities description: >- Explore entities associated with your search filters to reveal deeper connections. This endpoint retrieves the top N entities ranked by chunk volume and headline volume, merges the two sets, and returns entities with combined or individual counts. requestBody: required: true content: application/json: schema: type: object properties: query: type: object properties: text: type: string description: >- Natural-language search string. It is not mandatory when filtering by entities or keywords with the filters below. example: Tariffs impact in China 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 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. entity_categories: type: array description: >- Filter co-mentions by entity category. If not specified, all entity categories are included. items: type: string enum: - places - companies - organizations - people - products - concepts limit: type: integer description: >- Maximum number of entities to retrieve. It must be lower than or equal to 1000. example: 10 required: - query example: query: text: Type a theme to get connected entities... responses: '200': description: Entities co-mentions results content: application/json: schema: type: object properties: results: type: object description: >- Object containing arrays of different entity types that are co-mentioned with the search query. properties: places: type: array description: >- Array of places (countries, cities, regions) co-mentioned with the search query. items: type: object properties: id: type: string description: Unique entity identifier. example: 13FF12 total_chunks_count: type: integer description: >- Total number of chunks where this entity appears. example: 92468 total_headlines_count: type: integer description: >- Total number of titles where this entity appears. example: 24049 required: - id - total_chunks_count - total_headlines_count companies: type: array description: Array of companies co-mentioned with the search query. items: type: object properties: id: type: string description: Unique entity identifier. example: 275B6C total_chunks_count: type: integer description: >- Total number of chunks where this entity appears. example: 0 total_headlines_count: type: integer description: >- Total number of titles where this entity appears. example: 105 required: - id - total_chunks_count - total_headlines_count organizations: type: array description: >- Array of organizations co-mentioned with the search query. items: type: object properties: id: type: string description: Unique entity identifier. example: 1BC945 total_chunks_count: type: integer description: >- Total number of chunks where this entity appears. example: 17812 total_headlines_count: type: integer description: >- Total number of titles where this entity appears. example: 2427 required: - id - total_chunks_count - total_headlines_count people: type: array description: Array of people co-mentioned with the search query. items: type: object properties: id: type: string description: Unique entity identifier. example: 22C3AF total_chunks_count: type: integer description: >- Total number of chunks where this entity appears. example: 29883 total_headlines_count: type: integer description: >- Total number of titles where this entity appears. example: 22536 required: - id - total_chunks_count - total_headlines_count products: type: array description: Array of products co-mentioned with the search query. items: type: object properties: id: type: string description: Unique entity identifier. total_chunks_count: type: integer description: >- Total number of chunks where this entity appears. total_headlines_count: type: integer description: >- Total number of titles where this entity appears. required: - id - total_chunks_count - total_headlines_count concepts: type: array description: Array of concepts co-mentioned with the search query. items: type: object properties: id: type: string description: Unique entity identifier. example: 9DB5BD total_chunks_count: type: integer description: >- Total number of chunks where this entity appears. example: 106720 total_headlines_count: type: integer description: >- Total number of titles where this entity appears. example: 44591 required: - id - total_chunks_count - total_headlines_count required: - places - companies - organizations - people - products - concepts metadata: type: object description: Request metadata and timing information. properties: request_id: type: string description: Unique identifier for the request. example: 0f763fb3-4957-430a-acf6-5d4fc6b5109d timestamp: type: string format: date-time description: Timestamp when the response was generated. example: '2025-10-02T15:25:28.214117+00:00' 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: 1 required: - api_query_units required: - results components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````