Reading relationships

"Who is connected to this company?" has an answer in the reporting: who journalists write about alongside it, how often, and in which stories. This guide goes from a name to that answer, and to a sentence you can defend.

The four relationship tools count co-mentions, the articles that name two entities together. The worked example below follows one question through three calls, then covers what changed and what a watchlist shares. The figures are illustrative. Relationships is the reference.

1. Resolve the name

The relationship tools take entity ids, not names. Get one first:

{
  "name": "resolve_entity",
  "arguments": { "q": "ASML Holding NV", "type": "organization", "from": "2026-08-01", "to": "2026-08-31" }
}

{
  "entities": [
    {
      "entity_id": "organization:asml",
      "canonical": "asml",
      "aliases": [
        { "value": "asml", "count": 1240, "match": "exact" },
        { "value": "asml holding nv", "count": 31, "match": "exact" }
      ],
      "articles": 1271,
      "confidence": 1.0,
      "entity_resolution_version": "er-v1"
    }
  ]
}

One group at confidence 1.0, so organization:asml is the id. Several groups would mean the name is ambiguous: pick by articles, or ask. Use the same window for every call that follows. An id is resolved to its spellings within the window it is used in.

2. Who is reported alongside it

{
  "name": "related_entities",
  "arguments": {
    "entity_id": "organization:asml",
    "from": "2026-08-01",
    "to": "2026-08-31",
    "types": "organization,person",
    "limit": 10,
    "evidence": 3
  }
}

The first four rows of related, with the seed's articles at 1,271:

Reading co_mentions against sources and stories

co_mentions counts articles, and articles repeat. Read it next to the two counts that say how the articles were spread.

• tsmc: 212 articles in 64 stories, across the whole month. The two are written about together again and again, event after event. That is a pattern in the reporting.
• christophe fouquet: 71 stories. A person named alongside a company in that many separate events is part of how the company is covered, whatever the tie between them is.
• nvidia: 97 articles, but 4 stories in five days, carried by 90 outlets. That is an episode, not a pattern: a few events, syndicated widely. Read the evidence to see what they were before saying anything.
• imec: below the evidence cut, so it has counts only, and the count is an upper bound. Raise evidence, or ask connection_path about that pair, before quoting it.

sources is publishers, not newsrooms. A wire service or an ownership group puts one report on many domains, so more sources means wider distribution, not independent confirmation.

Why share matters more than the count

share is co_mentions over the articles that mention the entity you started from (on a path's second hop, the entity it ends at). For a small seed the count and the share tell the same story. For a large one they do not.

Start from location:united states and every large company has thousands of co-mentions, because the seed is in hundreds of thousands of articles. Ranked by count, the list is mostly a ranking of who gets covered at all. A company with 2,400 co-mentions there has a share of 0.005. Here, TSMC's 212 with ASML is a share of 0.167: it is in a sixth of ASML's coverage. Compare shares whenever the seeds, or the windows, differ in size.

3. How two entities connect

{
  "name": "connection_path",
  "arguments": {
    "from_entity": "organization:asml",
    "to_entity": "organization:rapidus",
    "from": "2026-08-01",
    "to": "2026-08-31",
    "evidence": 2
  }
}

{
  "direct": { "entity_id": "organization:rapidus", "co_mentions": 14, "stories": 6, "sources": 12, "evidence": ["..."] },
  "paths": [
    { "hops": ["organization:asml", "organization:tokyo electron", "organization:rapidus"], "strength": 9 },
    { "hops": ["organization:asml", "location:hokkaido japan", "organization:rapidus"], "strength": 7 }
  ],
  "credits_charged": 15
}

direct is the only part that puts both in one article: 14 of them, in 6 stories. Each path chains two separate co-mentions. ASML is reported with Tokyo Electron, and Tokyo Electron with Rapidus, in different articles. strength is the thinner of the two links. A path says the two share a neighbour in the reporting. It does not say one reaches the other through it.

An empty paths is not "unconnected". Only each end's strongest neighbours are compared, within the window you gave.

What changed

"Is anything different about who ASML is reported with?" is entity_network with a comparison window. Ask for counts only; the evidence comes after, for the changes you intend to report.

{
  "name": "entity_network",
  "arguments": {
    "entity_id": "organization:asml",
    "from": "2026-08-01",
    "to": "2026-08-31",
    "compare_from": "2026-07-01",
    "compare_to": "2026-07-31",
    "types": "organization,person",
    "evidence": 0
  }
}

changes lists the neighbours that are new and gone, and the ties that strengthened (share up by half or more) or weakened (down by a third). Shares are over each window's own coverage, so a busier month does not strengthen everything.

• A new neighbour means journalists started writing about the two together. One big story can do that. Call related_entities or connection_path for the pair and read its stories before calling it a development.
• gone is a neighbour that dropped well out of this window's reporting. It does not mean a relationship ended.
• The comparison is two passes, and both are charged. Keep the windows the same length, or the shares measure different amounts of time.

What a watchlist shares

For a set of entities, shared_exposures describes the reporting that names all of them: how much, where, and in what register.

{
  "name": "shared_exposures",
  "arguments": {
    "entity_id": "organization:asml,organization:tsmc,organization:samsung electronics",
    "from": "2026-08-01",
    "to": "2026-08-31",
    "facets": ["country", "topic"],
    "signal_stats": "supply_disruption,trade",
    "evidence": 5
  }
}

• articles, stories and sources: how much reporting names all three.
• facets: which countries and topics that reporting is about.
• signals: the mean and 95th percentile intensity of each signal over those articles. A high supply_disruption says the shared reporting reads as disruption, not that the companies are disrupted.
• evidence: the newest shared articles, to read.

Every id must appear in an article for the article to count, so three or five ids quickly narrow to little. Check each entry's aliases_used in entities: one empty list empties the whole result. For which pairs on a watchlist are reported together, call once per pair and compare articles and stories.

Saying it

Every number in this guide counts articles that name two entities together. That is evidence that journalists wrote about them together, and nothing more. It is not evidence of ownership, partnership, supply, funding, causation or exposure. A co-mention cannot tell a partner from a rival, a customer from a competitor, or a company from the example beside it in a market survey. Quote the evidence, name the outlets and the dates, and write "reported together in 64 stories in August", never "partners". Every response carries the same caveat as note, so it can travel with the data into whatever your agent writes.

Before concluding anything

• An empty aliases_used on a seed means the id matched nothing in the window. Widen the window or resolve the name again. It is not an entity with no connections.
• partial, coverage and from_clamped apply as on any search. A short list from a partial answer is not a small network. Reading completeness has the rule.
• approximate: true on an edge is an upper bound. Edges with evidence are recounted.
• indexed_through older than you expected means the newest reporting is not in the index yet.
• An empty evidence on a strong edge means the edge was below the evidence cut or the call's query budget was spent. It does not mean there are no articles.