Graph

Generate constellation graph data from the intelligence layer. The Graph API exposes Layer 3's view of the information landscape — story clusters, entity relationships, and narrative threads as an interconnected network ready for visualization or downstream analysis.

Pro+ feature. All Graph endpoints require a Professional or Enterprise tier API key. The graph is built continuously by Layer 3 as new articles are processed — data density improves as corpus volume grows. See Layer 3 for architecture details.

Constellation graph

GET /v1/graph

Generate a full constellation graph for a topic or time window. Returns nodes (story clusters and entities) and weighted edges (relationships between them) in a format suitable for force-directed visualization or graph analysis libraries.

Parameter	Type	Description
topic	string	Topic or keyword to center the graph on. Omit for a broad view of the current information landscape.
time_range	string	Lookback window: `1h`, `6h`, `24h`, `7d`, `30d`. Default: `7d`
layout	enum	Layout hint for positioning: `force` · `hierarchical` · `circular`. Default: `force`
max_nodes	integer	Maximum nodes to return. Default: `100`
entity_types	array	Filter node types: `PERSON` · `ORG` · `GPE` · `LOC` · `cluster`

BASH

curl "https://api.polariapi.com/v1/graph?topic=Iran+nuclear&time_range=7d&layout=force&max_nodes=50"
            \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "nodes": [
            {
            "id": "clus_9x3k2m8f",
            "label": "Iran Nuclear Talks Stall",
            "type": "cluster",
            "size": 52,
            "sentiment": -0.41,
            "metadata": {
            "article_count": 52,
            "source_count": 14,
            "first_seen": "2025-11-01T08:00:00Z",
            "last_updated": "2025-11-05T14:20:00Z"
            }
            },
            {
            "id": "ent_4k2m9x7p",
            "label": "Abbas Araghchi",
            "type": "PERSON",
            "size": 18,
            "sentiment": -0.28,
            "metadata": {
            "mentions": 187
            }
            }
            ],
            "edges": [
            {
            "source": "clus_9x3k2m8f",
            "target": "ent_4k2m9x7p",
            "strength": 0.87,
            "type": "contains"
            },
            {
            "source": "clus_9x3k2m8f",
            "target": "clus_7m2k3x9f",
            "strength": 0.72,
            "type": "shared_entities"
            }
            ],
            "layout_metadata": {
            "algorithm": "force-directed",
            "iterations": 100,
            "node_count": 48,
            "edge_count": 112
            }
            }
          

Cluster graph relationships

GET /v1/graph/cluster/{cluster_id}/relationships

Retrieve pre-computed graph relationships for a specific story cluster — the edges Layer 3 has built between this cluster and others across the full corpus. Returns all outbound relationships regardless of target, sorted by confidence descending.

Confidence values follow a discrete scale reflecting relationship signal strength:

Confidence	Signal
`0.4`	Weak — some entity overlap, possibly coincidental
`0.6`	Moderate — meaningful shared entities or narrative thread
`0.8`	Strong — significant overlap across multiple entity types
`1.0`	Definitive — same story, same entities, likely near-duplicate clusters

BASH

curl
            https://api.polariapi.com/v1/graph/cluster/clus_9x3k2m8f/relationships \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "cluster_id": "clus_9x3k2m8f",
            "relationships": [
            {
            "source": "clus_9x3k2m8f",
            "target": "clus_7m2k3x9f",
            "type": "shared_entities",
            "confidence": 0.8
            },
            {
            "source": "clus_9x3k2m8f",
            "target": "clus_2k9x4m3f",
            "type": "shared_entities",
            "confidence": 0.6
            }
            ]
            }
          

On graph density. Layer 3 builds cluster relationships continuously as new articles are processed. A cluster with zero relationships in this endpoint doesn't mean it's isolated — it means the graph hasn't yet built edges for that cluster against your current topic set. For on-demand relationship computation between a specific set of clusters, use Cluster relationships instead.

Node types

The constellation graph contains two categories of nodes:

Type	Represents	Size field
`cluster`	A story cluster from Layer 2 — a group of related articles across sources	Article count
`PERSON` · `ORG` · `GPE` · `LOC`	Named entities extracted by Layer 1 that appear prominently across clusters	Mention count

Edge types

Type	Description
`contains`	A cluster node → entity node edge indicating the entity appears within that cluster's articles
`shared_entities`	Cluster → cluster edge indicating overlapping named entities between two story clusters
`co_mention`	Entity → entity edge indicating two entities frequently appear in the same articles
`narrative_thread`	Cluster → cluster edge indicating sequential story evolution — one cluster developed into or continued another

← Previous

Relationships

Trends