Skip to main content

​
Overview

The get_media_event_cluster tool provides a deep-dive into a single story cluster discovered via get_media_events. It returns the cluster’s top-ranked articles, common entities, resolved metrics, and supports filters to explore specific angles of the story.
Always pass the same date and days values you used in get_media_events to ensure efficient queries.

​
Parameters

​
cluster_id
string
required
The cluster ID to fetch. Obtained from a get_media_events response.
​
date
string
Anchor/end date in YYYY-MM-DD format. Must match the date used in get_media_events. Defaults to today UTC.
​
days
integer
default:"1"
Lookback window in days. Must match the days used in get_media_events. Max 30.
​
detail
string
default:"summary"
Response detail level.
Level~TokensDescription
summary~500Voting articles (URL, title, domain, date, geo) + top 10 common entities + resolved metrics
standard~1,500Adds event metrics/actors to voting articles, top 5 entities per article, paginated additional articles
full~3,000+All entities per voting article, top 10 entities per paginated article, quad_classes
​
limit
integer
default:"10"
Number of additional articles beyond voting articles (standard/full only). Max 50.
​
offset
integer
default:"0"
Pagination offset for additional articles (standard/full only).

​
Filters

Use filters to explore specific angles of a story:
​
actor_country
string
ISO-3 country code to filter by actor nationality. Example: CHN to see how China is involved.
​
location
string
FIPS 2-letter code to filter by event location. Example: IR for events in Iran.
​
language
string
ISO 639-1 code to filter by article language. Example: fr for French-language coverage.
​
domain
string
Filter to articles from a specific source domain. Example: reuters.com.

​
Response Shape

​
Summary (default)

{
  "success": true,
  "cluster": {
    "cluster_id": "abc123",
    "cluster_label": "UN Security Council convenes for urgent meeting",
    "category": "conflict_security",
    "scope": "global",
    "article_count": 81,
    "total_events": 340
  },
  "resolved_metrics": {
    "avg_goldstein": -2.7,
    "avg_tone": -3.4,
    "primary_quad_class": 3,
    "primary_event": { "description": "Use conventional military force" },
    "primary_location": { "country_name": "Iran", "adm1_name": "Tehran" }
  },
  "voting_articles": [
    {
      "source_url": "https://...",
      "page_title": "UN calls emergency session on Iran tensions",
      "domain": "reuters.com",
      "article_weight": 0.72,
      "article_date": "2025-02-27",
      "article_lang": "en",
      "geo_country_name": "Iran"
    }
  ],
  "common_entities": [
    { "name": "Iran", "type": "organization" },
    { "name": "united nations", "type": "organization" }
  ],
  "metadata": {
    "total_count": 81,
    "voting_article_count": 5,
    "common_entity_count": 10,
    "common_entity_total": 42
  }
}

​
Standard / Full

Adds articles array (paginated additional articles beyond the top 5 voting articles), richer entity data per article, and pagination metadata (has_more, additional_total). When filters are applied, the response includes filtered_count showing how many articles match.

​
Usage Examples

# Basic deep-dive
GET /api/v1/media-events/cluster?cluster_id=abc123&detail=summary

# How is China involved in this story?
GET /api/v1/media-events/cluster?cluster_id=abc123&actor_country=CHN

# French-language coverage only
GET /api/v1/media-events/cluster?cluster_id=abc123&language=fr

# Paginate additional articles
GET /api/v1/media-events/cluster?cluster_id=abc123&detail=standard&limit=10&offset=10