Connected Entities

Explore entities co-mentioned with your keywords to reveal hidden connections, using powerful filtering tools.

POST /v1/search/co-mentions/entities

Try it

Connected Entities

cURL

curl --request POST \
  --url https://api.bigdata.com/v1/search/co-mentions/entities \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "query": {
    "text": "Tariffs impact in China",
    "filters": {
      "timestamp": {
        "start": "2023-11-07T05:31:56Z",
        "end": "2023-11-07T05:31:56Z"
      },
      "document_type": {
        "mode": "INCLUDE",
        "values": [
          "NEWS"
        ]
      },
      "source": {
        "mode": "INCLUDE",
        "values": [
          "ED68DC"
        ]
      },
      "category": {
        "mode": "INCLUDE",
        "values": [
          "expert_interviews",
          "news",
          "research"
        ]
      },
      "keyword": {
        "all_of": [],
        "any_of": [],
        "none_of": [
          "operating"
        ],
        "search_in": "HEADLINE"
      },
      "entity": {
        "all_of": [],
        "any_of": [
          "228D42"
        ],
        "none_of": [],
        "search_in": "HEADLINE"
      },
      "sentiment": {
        "ranges": [
          {
            "min": -1,
            "max": -0.3
          },
          {
            "min": 0.3,
            "max": 1
          }
        ],
        "values": [
          "positive",
          "negative",
          "neutral"
        ]
      },
      "reporting_entities": [
        "228D42"
      ],
      "reporting_periods": [
        {
          "fiscal_year": 2024,
          "fiscal_quarter": 3
        }
      ],
      "topic": {
        "all_of": [],
        "any_of": [
          "business,stock-prices,stock-price-volatility,down,"
        ],
        "none_of": [],
        "search_in": "HEADLINE"
      },
      "tag": {
        "any_of": [
          "research-report",
          "any-tag"
        ]
      }
    },
    "limit": 10
  }
}
'

200

{
  "results": {
    "places": [
      {
        "id": "13FF12",
        "total_chunks_count": 92468,
        "total_headlines_count": 24049
      }
    ],
    "companies": [
      {
        "id": "275B6C",
        "total_chunks_count": 0,
        "total_headlines_count": 105
      }
    ],
    "organizations": [
      {
        "id": "1BC945",
        "total_chunks_count": 17812,
        "total_headlines_count": 2427
      }
    ],
    "people": [
      {
        "id": "22C3AF",
        "total_chunks_count": 29883,
        "total_headlines_count": 22536
      }
    ],
    "products": [
      {
        "id": "<string>",
        "total_chunks_count": 123,
        "total_headlines_count": 123
      }
    ],
    "concepts": [
      {
        "id": "9DB5BD",
        "total_chunks_count": 106720,
        "total_headlines_count": 44591
      }
    ]
  },
  "metadata": {
    "request_id": "0f763fb3-4957-430a-acf6-5d4fc6b5109d",
    "timestamp": "2025-10-02T15:25:28.214117+00:00"
  },
  "usage": {
    "api_query_units": 1
  }
}

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 or keywords with the filters below.

Example:

"Tariffs impact in China"

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. limit · integer

Maximum number of entities to retrieve. It must be lower than or equal to 1000.

Example:

10

Response

200 - application/json

Entities co-mentions results

results · object · required

Object containing arrays of different entity types that are co-mentioned with the search query.

Show child attributes

results. places · object[] · required

Array of places (countries, cities, regions) co-mentioned with the search query.

Show child attributes

results.places. id · string · required

Unique entity identifier.

Example:

"13FF12"

results.places. total_chunks_count · integer · required

Total number of chunks where this entity appears.

Example:

92468

results.places. total_headlines_count · integer · required

Total number of titles where this entity appears.

Example:

24049

results. companies · object[] · required

Array of companies co-mentioned with the search query.

Show child attributes

results.companies. id · string · required

Unique entity identifier.

Example:

"275B6C"

results.companies. total_chunks_count · integer · required

Total number of chunks where this entity appears.

Example:

0

results.companies. total_headlines_count · integer · required

Total number of titles where this entity appears.

Example:

105

results. organizations · object[] · required

Array of organizations co-mentioned with the search query.

Show child attributes

results.organizations. id · string · required

Unique entity identifier.

Example:

"1BC945"

results.organizations. total_chunks_count · integer · required

Total number of chunks where this entity appears.

Example:

17812

results.organizations. total_headlines_count · integer · required

Total number of titles where this entity appears.

Example:

2427

results. people · object[] · required

Array of people co-mentioned with the search query.

Show child attributes

results.people. id · string · required

Unique entity identifier.

Example:

"22C3AF"

results.people. total_chunks_count · integer · required

Total number of chunks where this entity appears.

Example:

29883

results.people. total_headlines_count · integer · required

Total number of titles where this entity appears.

Example:

22536

results. products · object[] · required

Array of products co-mentioned with the search query.

Show child attributes

results.products. id · string · required

Unique entity identifier.

results.products. total_chunks_count · integer · required

Total number of chunks where this entity appears.

results.products. total_headlines_count · integer · required

Total number of titles where this entity appears.

results. concepts · object[] · required

Array of concepts co-mentioned with the search query.

Show child attributes

results.concepts. id · string · required

Unique entity identifier.

Example:

"9DB5BD"

results.concepts. total_chunks_count · integer · required

Total number of chunks where this entity appears.

Example:

106720

results.concepts. total_headlines_count · integer · required

Total number of titles where this entity appears.

Example:

44591

metadata · object

Request metadata and timing information.

Show child attributes

metadata. request_id · string · required

Unique identifier for the request.

Example:

"0f763fb3-4957-430a-acf6-5d4fc6b5109d"

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

Timestamp when the response was generated.

Example:

"2025-10-02T15:25:28.214117+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:

1