Skip to main content
GET
/
api
/
v1
/
media-events
Top Media Event Clusters
curl --request GET \
  --url https://gdeltcloud.com/api/v1/media-events \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "clusters": [
    {
      "cluster_id": "<string>",
      "cluster_label": "<string>",
      "category": "politics_governance",
      "scope": "local",
      "time_bucket": "2023-11-07T05:31:56Z",
      "article_count": 123,
      "total_events": 123,
      "resolved_metrics": {
        "primary_actor1": {
          "code": "<string>",
          "name": "<string>",
          "country_code": "<string>",
          "country_name": "<string>"
        },
        "primary_actor2": {
          "code": "<string>",
          "name": "<string>",
          "country_code": "<string>",
          "country_name": "<string>"
        },
        "primary_event": {
          "code": "<string>",
          "root_code": "<string>",
          "description": "<string>"
        },
        "primary_location": {
          "country_code": "<string>",
          "country_name": "<string>",
          "adm1_code": "<string>",
          "adm1_name": "<string>",
          "lat": 123,
          "long": 123
        },
        "avg_goldstein": 123,
        "avg_tone": 123,
        "primary_quad_class": 123,
        "top_entities": [
          {
            "name": "<string>",
            "frequency": 123
          }
        ],
        "languages": [
          "<string>"
        ],
        "resolution_article_count": 123
      },
      "representative_articles": [
        {
          "cluster_id": "<string>",
          "cluster_label": "<string>",
          "article_weight": 123,
          "category": "politics_governance",
          "scope": "local",
          "avg_goldstein": 123,
          "avg_tone": 123,
          "quad_classes": [
            123
          ],
          "event_code": "14",
          "event_description": "Protest",
          "actor1_name": "<string>",
          "actor2_name": "<string>",
          "actor1_country_code": "USA",
          "actor2_country_code": "CHN",
          "geo_country_name": "<string>",
          "geo_adm1_name": "<string>",
          "source_url": "<string>",
          "page_title": "<string>",
          "domain": "reuters.com",
          "article_date": "2023-12-25",
          "sharing_image": "<string>",
          "linked_entities": [
            {
              "name": "<string>",
              "canonical_name": "<string>",
              "type": "person"
            }
          ]
        }
      ],
      "linked_entities": [
        {
          "name": "<string>",
          "canonical_name": "<string>",
          "type": "person"
        }
      ]
    }
  ],
  "filters": {},
  "metadata": {
    "cluster_count": 123,
    "execution_time_ms": 123
  }
}

Authorizations

​
Authorization
string
header
required

API key format: gdelt_sk_<64-hex-chars>. Generate in Dashboard → Settings → API Keys.

Query Parameters

​
days
integer
default:1

Window size in days ending on date. days=1 returns only the date bucket. days=7 returns 7 daily buckets ending on date. Max 30.

Required range: 1 <= x <= 30
Example:

1

​
date
string<date>

Anchor/end date of the time window (YYYY-MM-DD). Defaults to today UTC. Example: date=2025-02-20 + days=7 returns Feb 14–20.

Example:

"2025-02-20"

​
limit
integer
default:10

Number of clusters to return.

Required range: 1 <= x <= 50
​
offset
integer
default:0

Number of clusters to skip for pagination. Pass offset=10 for the second page, offset=20 for the third, etc.

Required range: x >= 0
Example:

10

​
detail
enum<string>
default:full

Response detail level. summary (~120 tokens/cluster): compact headline card with cluster_id, label, category, scope, article_count, key metrics, 3 top entity names, 3 top source domains. No articles. standard (~500 tokens/cluster): resolved metrics + 5 article reference cards (url, title, domain, date) + 10 entity reference cards (name, type). full (~1000 tokens/cluster, default): resolved metrics + 5 article reference cards (+ weight, geo, lang) + all entity reference cards (+ wikipedia_url).

Available options:
summary,
standard,
full
​
category
enum<string>

Filter by topic category.

Available options:
conflict_security,
politics_governance,
crime_justice,
economy_business,
science_health,
disaster_emergency,
society_culture,
technology
​
scope
enum<string>

Filter by geographic scope.

Available options:
local,
national,
global
​
actor_country
string

CAMEO ISO-3 country code for actor1 or actor2 (e.g. USA, GBR, CHN).

Example:

"USA"

​
event_type
string

CAMEO event root code prefix (e.g. '14'=Protest, '18'=Assault, '19'=Fight).

Example:

"14"

​
location
string

ADM1 2-letter country prefix matching action_geo_adm1_code (e.g. 'US' matches US01, US06, etc.).

Example:

"US"

​
language
string

Filter clusters to those containing articles in this language (e.g. 'English', 'Spanish', 'French').

Example:

"English"

​
domain
string

Filter to clusters containing at least one article from this domain.

Example:

"reuters.com"

​
goldstein_min
number

Post-resolution filter: minimum resolved Goldstein scale value.

Required range: -10 <= x <= 10
​
goldstein_max
number

Post-resolution filter: maximum resolved Goldstein scale value.

Required range: -10 <= x <= 10
​
tone_min
number

Post-resolution filter: minimum resolved average tone value.

​
tone_max
number

Post-resolution filter: maximum resolved average tone value.

​
quad_class
enum<integer>

Post-resolution filter: quad class. 1=Verbal Cooperation, 2=Material Cooperation, 3=Verbal Conflict, 4=Material Conflict.

Available options:
1,
2,
3,
4
​
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 (date, category, scope, actor_country, event_type, location, language, domain). Examples: 'climate change protests', 'AI regulation European Union', 'Middle East ceasefire negotiations'.

Example:

"trade war tariffs China"

Response

Success

​
success
boolean
​
clusters
object[]

Resolved media event clusters, each with metrics, representative articles, and linked entities.

​
filters
object
​
metadata
object