Skip to main content

​
Overview

The get_media_events tool is the primary discovery tool — use it to scan what’s happening in the news. It returns the top story clusters (Media Events) ranked by significance, each representing a group of articles covering the same story.
This is the starting point for most queries. Use the returned cluster_id values to drill into specific stories with get_media_event_cluster.

​
Parameters

​
days
integer
default:"1"
Window size in days ending on date. days=1 returns clusters for the single date only. days=7 returns 7 daily buckets ending on date. Max 30.
​
date
string
Anchor/end date in YYYY-MM-DD format. Defaults to today UTC. Example: date=2025-02-20 with days=7 returns Feb 14–20.
​
limit
integer
default:"10"
Number of clusters to return. Max 20. Keep small (5-10) for scanning.
​
offset
integer
default:"0"
Pagination offset. Pass offset=10 for the second page.
​
detail
string
default:"summary"
Response detail level. Controls how much data per cluster.
Level~Tokens/ClusterIncludes
summary~120Headline card: cluster_id, label, category, scope, article_count, key metrics, 3 entity names, 3 source domains. No articles.
standard~500Resolved metrics + 5 article ref cards (url, title, domain, date) + 10 entity ref cards
full~1,000Richer article ref cards (+ weight, geo, lang) + all entity ref cards (+ wikipedia_url)
10 clusters at full detail ≈ 10,000 tokens. Always start with summary and escalate only when needed.
​
search
string
Natural-language semantic search query. When provided, clusters are ranked by embedding similarity (cosine distance via HNSW ANN index) instead of article count. The query is embedded with text-embedding-3-small (768 dims) and matched against article cluster embeddings. Combinable with all other filters.Examples: trade war tariffs China, climate change protests, AI regulation European Union.

​
Filters

All filters combine as AND with each other and with search.
​
actor_country
string
WHO is involved — ISO-3 country code for actor nationality. Examples: USA, CHN, GBR, RUS.
​
location
string
WHERE it happened — FIPS 2-letter country code for event location. Examples: US, CH, UK, RS.
​
event_type
string
CAMEO event root code. Examples: 14=Protest, 18=Assault, 19=Fight, 05=Diplomacy.
​
category
string
Topic category: conflict_security, politics_governance, economy_business, crime_justice, science_health, disaster_emergency, society_culture, technology.
​
scope
string
Geographic scope: local, national, global.
​
language
string
ISO 639-1 language code (e.g. en, es, fr). Default is all languages.
​
domain
string
Filter to clusters containing articles from this domain (e.g. reuters.com).

​
Response Shape

​
Summary (~120 tokens/cluster)

{
  "clusters": [
    {
      "cluster_id": "abc123",
      "cluster_label": "US Senate votes on budget resolution",
      "category": "politics_governance",
      "scope": "national",
      "time_bucket": "2025-02-27T00:00:00Z",
      "article_count": 47,
      "avg_goldstein": -2.4,
      "avg_tone": -3.1,
      "quad_class": 3,
      "event_description": "Reject",
      "location": "Washington DC",
      "top_entities": ["chuck schumer", "mitch mcconnell"],
      "top_sources": ["apnews.com", "reuters.com"],
      "languages": ["English"]
    }
  ],
  "filters": { "days": 1, "date": "2025-02-27", "detail": "summary" },
  "metadata": { "cluster_count": 10 }
}

​
Standard (~500 tokens/cluster)

Adds resolved_metrics, 5 article reference cards, and 10 entity reference cards: 
{
  "clusters": [
    {
      "cluster_id": "abc123",
      "cluster_label": "...",
      "category": "politics_governance",
      "scope": "national",
      "article_count": 47,
      "resolved_metrics": {
        "avg_goldstein": -2.4,
        "avg_tone": -3.1,
        "primary_quad_class": 3,
        "primary_event": { "code": "12", "description": "Reject" },
        "primary_location": { "country_name": "United States", "adm1_name": "Washington" }
      },
      "articles": [
        { "source_url": "https://...", "page_title": "...", "domain": "apnews.com", "article_date": "2025-02-27" }
      ],
      "linked_entities": [
        { "name": "chuck schumer", "type": "person" }
      ]
    }
  ]
}

​
Full (~1,000 tokens/cluster)

Articles include article_weight, geo_country_name, article_lang. Entities include wikipedia_url.

​
Usage Examples

# Today's top stories (compact)
GET /api/v1/media-events?days=1&limit=10&detail=summary

# Semantic search — find stories about a topic
GET /api/v1/media-events?search=AI+regulation+policy&detail=summary

# Semantic search + category filter
GET /api/v1/media-events?search=trade+war+tariffs&category=economy_business&detail=summary

# Semantic search + actor + location
GET /api/v1/media-events?search=nuclear+negotiations&actor_country=IRN&location=US

# Conflict news involving Russia this week
GET /api/v1/media-events?days=7&actor_country=RUS&category=conflict_security&detail=summary

# Protests in France
GET /api/v1/media-events?days=7&location=FR&event_type=14&detail=standard

​
Workflow

1

Scan headlines or search

Call get_media_events(detail='summary', limit=10) to see what’s happening, or use search to find stories about a specific topic.
2

Drill into a story

Pick an interesting cluster and call get_media_event_cluster(cluster_id) to see all articles and entities.
3

Profile an entity

See a key person or organization? Call get_entity(canonical_name, type) for their full profile.