Relationships

Query connections between entities and story clusters. The Relationships API exposes two distinct relationship types: entity relationships (how named people, organizations, and places co-occur across articles) and cluster relationships (how story clusters share underlying entities and narrative threads).

Two relationship types. Entity relationships are built by Layer 3 from co-occurrence patterns across the full corpus. Cluster relationships can be queried two ways: the Layer 3 graph (pre-computed, high confidence, requires sufficient data density) or the Layer 2 entity overlap endpoint (computed on demand, always available, grounded in named entity extraction).

Entity relationships

GET /v1/relationships

Query relationships between named entities — how strongly two entities are connected based on co-occurrence patterns, context, and narrative proximity across the full article corpus.

Parameter	Type	Description
entity	string	Entity ID to map relationships from. Required.
depth	integer	Relationship traversal depth. Range: `1`–`3`. Default: `1`
min_strength	float	Minimum relationship strength to include. Range: `0.0`–`1.0`. Default: `0.5`
type	enum	Relationship type filter: `co_mention` · `causal` · `adversarial` · `collaborative`
time_range	string	Restrict to articles within window. Default: `30d`

BASH

curl "https://api.polariapi.com/v1/relationships?entity=ent_4k2m9x7p&depth=2&min_strength=0.6"
            \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "entity": {
            "id": "ent_4k2m9x7p",
            "name": "Benjamin Netanyahu"
            },
            "relationships": [
            {
            "target_entity": {
            "id": "ent_9x2m4k7f",
            "name": "Abbas Araghchi"
            },
            "strength": 0.81,
            "type": "adversarial",
            "co_mentions": 187,
            "contexts": ["nuclear talks", "ceasefire", "sanctions"],
            "sentiment": -0.54
            },
            {
            "target_entity": {
            "id": "ent_7m2k9x4p",
            "name": "Donald Trump"
            },
            "strength": 0.74,
            "type": "co_mention",
            "co_mentions": 234,
            "contexts": ["Middle East policy", "Gaza"],
            "sentiment": 0.12
            }
            ]
            }
          

Relationship network

GET /v1/relationships/network

Generate a network graph of entity relationships suitable for visualization. Returns nodes and weighted edges in a format compatible with standard graph libraries (D3, Sigma, Cytoscape).

Parameter	Type	Description
entity	string	Root entity ID. The network radiates outward from this node.
depth	integer	Traversal depth. Default: `2`
max_nodes	integer	Cap on returned nodes. Default: `50`
min_strength	float	Minimum edge strength to include. Default: `0.4`

RESPONSE
{
            "nodes": [
            {
            "id": "ent_4k2m9x7p",
            "name": "Benjamin Netanyahu",
            "type": "PERSON",
            "mentions": 342,
            "sentiment_avg": 0.23
            }
            ],
            "edges": [
            {
            "source": "ent_4k2m9x7p",
            "target": "ent_9x2m4k7f",
            "strength": 0.81,
            "type": "adversarial"
            }
            ]
            }
          

Cluster relationships

GET /v1/stories/relationships

Compute entity-based relationships between a specific set of story clusters. For each pair in the provided set, the API aggregates all named entities extracted by Layer 1 across the clusters' articles and returns weighted edges based on shared entity overlap.

This endpoint is complementary to the Layer 3 graph. The Layer 3 graph pre-computes relationships across the full corpus and is highest quality when data density is high. Cluster relationships are computed on demand for exactly the clusters you specify — always available regardless of corpus size, and grounded directly in Layer 1 named entity extraction.

Parameter	Type	Description
ids	string	Comma-separated list of cluster IDs. Min: `2`. Max: `20`. Required.
min_shared	integer	Minimum shared named entities required to return a relationship. Default: `3`

BASH

curl "https://api.polariapi.com/v1/stories/relationships?ids=clus_9x3k2m8f,clus_4m7k2x9f,clus_2x9m3k7f&min_shared=3"
            \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "cluster_count": 3,
            "relationships": [
            {
            "source": "clus_9x3k2m8f",
            "target": "clus_4m7k2x9f",
            "confidence": 0.158,
            "type": "shared_entities",
            "shared_count": 81,
            "shared_entities": [
            "Benjamin Netanyahu",
            "Abbas Araghchi",
            "Strait of Hormuz"
            ]
            }
            ],
            "computed_from": "layer1_entities"
            }
          

On confidence scores. Cluster relationship confidence is computed as Jaccard similarity over the named entity sets of each cluster — the size of the shared entity set divided by the union. Scores are intentionally lower than entity relationship strength values; a score of 0.15 across 80+ shared entities represents a strong thematic connection. Sort by shared_count for the most signal-dense pairs, or by confidence for the most topically distinct relationships.

Relationship types

The type field on entity relationships describes the nature of the connection as inferred from article context:

Type	Description
`co_mention`	Entities appear together in articles without a directional relationship inferred
`collaborative`	Entities are referenced in cooperative or aligned contexts — partnerships, agreements, joint actions
`adversarial`	Entities appear in opposing, conflicting, or competitive contexts
`causal`	One entity's actions are described as causing or influencing outcomes involving the other

Cluster relationships currently return shared_entities only. Directional relationship types between clusters are on the roadmap for Layer 3 v2.

← Previous

Clusters

Graph