Skip to main content
GET
/
api
/
v1
/
media-events
/
cluster
Deep-Dive Into a Cluster
curl --request GET \
  --url https://gdeltcloud.com/api/v1/media-events/cluster \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "cluster": {
    "cluster_id": "<string>",
    "cluster_label": "<string>",
    "category": "<string>",
    "scope": "<string>",
    "time_bucket": "<string>",
    "article_count": 123,
    "filtered_count": 123,
    "total_events": 123
  },
  "resolved_metrics": {
    "avg_goldstein": 123,
    "avg_tone": 123,
    "primary_quad_class": 123,
    "primary_event": {},
    "primary_location": {},
    "top_entities": [
      {}
    ],
    "languages": [
      "<string>"
    ]
  },
  "voting_articles": [
    {}
  ],
  "common_entities": [
    {
      "name": "<string>",
      "type": "person",
      "wikipedia_url": "<string>"
    }
  ],
  "articles": [
    {
      "source_url": "<string>",
      "page_title": "<string>",
      "domain": "reuters.com",
      "article_date": "2023-12-25",
      "article_weight": 123,
      "article_lang": "<string>",
      "geo_country_name": "<string>",
      "geo_adm1_name": "<string>",
      "sharing_image": "<string>",
      "linked_entities": [
        {
          "name": "<string>",
          "type": "person",
          "wikipedia_url": "<string>"
        }
      ]
    }
  ],
  "filters": {},
  "metadata": {
    "total_count": 123,
    "filtered_count": 123,
    "voting_article_count": 123,
    "common_entity_count": 123,
    "common_entity_total": 123,
    "page_count": 123,
    "additional_total": 123,
    "has_more": true,
    "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

cluster_id
string
required

The cluster ID to fetch (from a media-events response).

date
string<date>

Anchor/end date (YYYY-MM-DD). Should match the date used in the media-events discovery call. Defaults to today UTC.

Example:

"2025-02-27"

days
integer
default:1

Lookback window in days from date. Should match the days used in the media-events discovery call. Default 1.

Required range: 1 <= x <= 30
detail
enum<string>
default:summary

Response detail level. summary (~500 tokens): voting articles (URL, title, domain, date, geo) + top 10 common entities + resolved metrics. standard (~1500 tokens): adds event metrics/actors, top 5 entities per voting article, paginated additional articles. full (~3000+ tokens): all entities per voting article, top 10 per paginated article, quad_classes.

Available options:
summary,
standard,
full
actor_country
string

ISO-3 code to filter articles by actor nationality (e.g. 'CHN' to see how China is involved).

Example:

"CHN"

location
string

FIPS 2-letter code to filter articles by event geo location (e.g. 'IR' for Iran).

Example:

"IR"

language
string

ISO 639-1 code to filter articles by source language (e.g. 'en', 'fr', 'ar').

Example:

"en"

domain
string

Filter articles to a specific source domain.

Example:

"reuters.com"

category
enum<string>

Filter articles by topic category.

Available options:
conflict_security,
politics_governance,
crime_justice,
economy_business,
science_health,
disaster_emergency,
society_culture,
technology
limit
integer
default:10

Number of additional articles beyond voting articles (standard/full only). Default 10.

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

Pagination offset for additional articles (standard/full only).

Required range: x >= 0

Response

Success

success
boolean
cluster
object
resolved_metrics
object

CAMEO metrics resolved from top-ranked voting articles.

voting_articles
object[]

Top 5 ranked articles. Shape depends on detail level.

common_entities
object[]

Top GEG entities across voting articles (10 in summary, 20 in standard, all in full).

articles
object[]

Paginated additional articles beyond the top 5 voting articles (standard/full only). Each article includes source URL, title, domain, date, and enrichment data depending on detail level.

filters
object
metadata
object