GDELT Cloud Docs — Global Event Data API & MCP

Use API v2 for new integrations. v2 is the recommended interface for clean generated GDELT Cloud Events, clustered Stories, Entities, normalized geography, canonical significance ranking, top-3 inline articles, and cursor pagination. See API v2.API v1 remains supported for existing direct API users and integrations.

Overview

The GDELT Cloud v1 Developer API (/api/v1/*) provides backward-compatible programmatic access to earlier GDELT Cloud surfaces: media-event clusters, GEG entity profiles, news-domain profiles, Conflict events, and CAMEO+ events. For new dashboards, monitoring workflows, agents, and analyst applications, prefer /api/v2/*. V2 Event, Story, and Entity list endpoints default to the exact past 24 hours. Narrow with geography, category, subcategory, date windows up to 30 days, and semantic search rather than public confidence modes.

API v2

Recommended clean Events, Stories, Entities, geo discovery, summaries, and cursor pagination

Media Events

Legacy story clusters from articles, filterable by category, actor country, location, and event type

Entities

Wikipedia-linked GEG entity profiles with sentiment, linked stories, and relationship graph

Domains

News domain profiles — stats, top persons/orgs, recent articles

Authentication

All Developer API requests require an API key in the Authorization header:

Authorization: Bearer gdelt_sk_your_api_key_here

API keys use the format gdelt_sk_<64-hex-chars>. Generate yours in Dashboard → Settings → API Keys.

API keys require API access on your GDELT Cloud account.

curl "https://gdeltcloud.com/api/v1/media-events?days=1&limit=5&detail=summary" \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here"

import requests, os

resp = requests.get(
    "https://gdeltcloud.com/api/v1/media-events",
    headers={"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"},
    params={"days": 1, "limit": 5, "detail": "summary"}
)
data = resp.json()

const resp = await fetch(
  "https://gdeltcloud.com/api/v1/media-events?days=1&limit=5&detail=summary",
  { headers: { "Authorization": `Bearer ${process.env.GDELT_API_KEY}` } }
);
const data = await resp.json();

The equivalent v2 starting point is:

curl "https://gdeltcloud.com/api/v2/stories?date_start=2026-04-11&date_end=2026-04-17&limit=5&sort=significance" \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here"

Confidence Strictness Spectrum

Several GDELT Cloud product surfaces now use the same plain-language confidence spectrum:

High confidence → strict
Balanced → balanced
Broad → broad

For alerting, this appears as spec_json.filters.precision_mode. Plain-language meaning:

Label	API Value	Meaning
High confidence	`strict`	Only primary clusters with strong story-family confidence
Balanced	`balanced`	Primary clusters only
Broad	`broad`	Include weaker/supporting cluster families too

This is a quality gate, not a separate family filter. It combines with the rest of your filters using logical AND. It is now exposed directly on the main event-discovery APIs as the precision query parameter:

/api/v1/media-events
/api/v1/conflict-events
/api/v1/cameoplus-events

Date & Time Parameters

All v1 endpoints accept a consistent date + days pattern:

Param	Type	Default	Description
`date`	`YYYY-MM-DD`	today UTC	Anchor/end date of the window. Defaults to today UTC.
`days`	integer	varies	Window size in days ending on `date`. Max 30 for all endpoints.

Example: date=2025-02-20&days=7 returns data from Feb 14-20 (7 days ending on Feb 20).

For /api/v1/media-events specifically: days=1 returns only the single date daily bucket; days=7 returns 7 daily buckets ending on date.

Response Detail Levels

Most endpoints support a detail parameter for progressive disclosure — control how much data you receive to optimize for your use case.

`/api/v1/media-events`

Level	~Tokens/Cluster	Best For
`summary`	~120	Scanning headlines, MCP agent discovery, dashboards
`standard`	~500	Article links + actor/location details, intermediate analysis
`full`	~1,000	Complete data with per-article metrics, full integration (default)

# Compact summary cards for quick scanning
GET /api/v1/media-events?days=1&limit=10&detail=summary

# Standard detail with article links
GET /api/v1/media-events?days=7&limit=5&detail=standard

# Full data (default, backward-compatible)
GET /api/v1/media-events?days=1&limit=10&detail=full

summary returns compact headline cards: cluster_id, label, category, scope, time_bucket, article_count, avg_goldstein, avg_tone, quad_class, event_description, location, top 5 entity names, top 5 source domains, and languages. standard adds trimmed representative articles (URL, title, domain, date, weight), resolved actor/event/location details, and top 10 linked entities. full (default) returns the complete unmodified response including per-article metrics, all linked entities, and lat/long coordinates.

Summary Response Shape

{
  "clusters": [
    {
      "cluster_id": "abc123",
      "cluster_label": "French workers stage nationwide strikes",
      "category": "politics_governance",
      "scope": "national",
      "time_bucket": "2025-02-20T00:00:00Z",
      "article_count": 47,
      "avg_goldstein": -5.0,
      "avg_tone": -3.2,
      "quad_class": 3,
      "event_description": "Protest",
      "location": "France",
      "top_entities": ["Emmanuel Macron", "CGT", "Marine Le Pen"],
      "top_sources": ["reuters.com", "bbc.com", "lemonde.fr"],
      "languages": ["English", "French"]
    }
  ],
  "metadata": { "cluster_count": 10, "execution_time_ms": 120 }
}

Standard Response Shape

{
  "clusters": [
    {
      "cluster_id": "abc123",
      "cluster_label": "French workers stage nationwide strikes",
      "category": "politics_governance",
      "scope": "national",
      "article_count": 47,
      "resolved_metrics": {
        "primary_actor1": { "name": "France", "country_code": "FRA" },
        "primary_event": { "code": "14", "description": "Protest" },
        "primary_location": { "country_name": "France", "adm1_name": "Ile-de-France" },
        "avg_goldstein": -5.0,
        "avg_tone": -3.2
      },
      "representative_articles": [
        {
          "source_url": "https://reuters.com/...",
          "page_title": "French workers walk out in nationwide strike",
          "domain": "reuters.com",
          "article_date": "2025-02-20",
          "article_weight": 0.72
        }
      ],
      "linked_entities": [
        { "name": "Emmanuel Macron", "type": "person" },
        { "name": "CGT", "type": "organization" }
      ]
    }
  ]
}

For MCP agents: Start with detail=summary to discover what’s happening, then use the cluster endpoint to deep-dive into specific stories.

`/api/v1/media-events/cluster`

Level	~Tokens	Description
`summary`	~500	Voting articles (URL, title, domain, date, geo) + top 10 common entities + resolved metrics
`standard`	~1,500	Adds event metrics/actors, top 5 entities per voting article, paginated additional articles
`full`	~3,000+	All entities per voting article, top 10 per paginated article, quad_classes

Summary Response Shape

{
  "success": true,
  "cluster": {
    "cluster_id": "abc123",
    "cluster_label": "UN Security Council convenes for urgent meeting",
    "category": "conflict_security",
    "scope": "global",
    "article_count": 81
  },
  "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 Security Council holds emergency session",
      "domain": "cnn.com",
      "article_weight": 0.72,
      "article_date": "2025-02-27",
      "geo_country_name": "Iran"
    }
  ],
  "common_entities": [
    { "name": "Iran", "type": "organization", "wikipedia_url": "https://..." }
  ],
  "metadata": {
    "total_count": 81,
    "voting_article_count": 5,
    "common_entity_count": 10
  }
}

Standard Response Shape

{
  "success": true,
  "cluster": { "cluster_id": "abc123", "article_count": 81 },
  "resolved_metrics": { "..." : "same as summary + actor details" },
  "voting_articles": [
    {
      "source_url": "https://...",
      "page_title": "...",
      "domain": "cnn.com",
      "article_date": "2025-02-27",
      "article_weight": 0.72,
      "geo_country_name": "Iran",
      "linked_entities": [
        { "name": "Iran", "type": "organization" },
        { "name": "United Nations", "type": "organization" }
      ]
    }
  ],
  "articles": [
    {
      "source_url": "https://...",
      "page_title": "...",
      "domain": "bbc.com",
      "article_date": "2025-02-27"
    }
  ],
  "common_entities": [ "..." ],
  "metadata": {
    "total_count": 81,
    "voting_article_count": 5,
    "page_count": 10,
    "additional_total": 76,
    "has_more": true
  }
}

`/api/v1/entity-geg`

Level	~Tokens	Description
`summary`	~300	Entity basics + 3 story ref cards + 10 co-occurrence ref cards. No timeline.
`standard`	~1,200	Full entity master + 20 story refs + 25 co-occ refs + timeline
`full`	~1,500	Full entity master + paginated story refs + 50 co-occ refs + timeline

Cluster Deep-Dive (`/api/v1/media-events/cluster`)

After discovering stories with /api/v1/media-events, drill into a specific cluster to see all articles, key entities, and apply filters.

Parameters

Param	Type	Default	Description
`cluster_id`	string	required	Cluster ID from a `media-events` response
`date`	`YYYY-MM-DD`	today UTC	Same date used in the discovery call
`days`	integer	`1`	Same window used in the discovery call (max 30)
`detail`	string	`summary`	`summary`, `standard`, or `full`
`actor_country`	string	—	ISO-3 code to filter by actor nationality (e.g. `CHN`, `USA`)
`location`	string	—	FIPS 2-letter to filter by event location (e.g. `IR`, `US`)
`language`	string	—	ISO 639-1 to filter by article language (e.g. `en`, `fr`)
`domain`	string	—	Filter to a specific source domain
`category`	string	—	Filter by topic category
`limit`	integer	`10`	Additional articles (standard/full only, max 50)
`offset`	integer	`0`	Pagination for additional articles

Filters

Use filters to explore specific angles of a story:

# 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

# Only Reuters articles
GET /api/v1/media-events/cluster?cluster_id=abc123&domain=reuters.com

When filters are applied, the response includes filtered_count showing how many articles match.

Always pass date and days matching the media-events discovery call to ensure efficient partition-scoped queries.

Semantic Search (`/api/v1/media-events`)

The search parameter enables natural-language semantic search across media event clusters. When provided, clusters are ranked by embedding similarity (cosine distance) instead of article count.

# Find stories about AI regulation
GET /api/v1/media-events?search=AI+regulation+European+Union&detail=summary

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

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

# Semantic search over a week
GET /api/v1/media-events?search=climate+change+protests&days=7&detail=summary

How it works

Your query text is converted server-side into a semantic representation
Matching records are scored against pre-computed article representations
Results are grouped by cluster and ranked by semantic similarity

Combining with filters

All filters work with search — they combine as AND (each filter narrows results):

Filter	Works with `search`?	How it’s applied
`date` / `days`	✅	Time window constraint
`category`	✅	Cluster-level pre-filter
`scope`	✅	Cluster-level pre-filter
`actor_country`	✅	Event-level pre-filter (restricts article candidates before ANN)
`event_type`	✅	Event-level pre-filter
`location`	✅	Event-level pre-filter
`language`	✅	Language pre-filter
`domain`	✅	Domain pre-filter
`goldstein_min/max`, `tone_min/max`, `quad_class`	✅	Post-resolution filter

Semantic search is best for conceptual queries — topics, themes, or ideas described in natural language. Use structured filters for precise criteria like specific countries, event types, or date ranges. Combine both for the most targeted results.

Pagination (`/api/v1/media-events`)

/api/v1/media-events supports numeric offset pagination via the offset parameter:

Param	Type	Default	Description
`offset`	integer	`0`	Number of clusters to skip.

# Page 1 (first 10)
GET /api/v1/media-events?days=1&limit=10&offset=0

# Page 2 (next 10)
GET /api/v1/media-events?days=1&limit=10&offset=10

# Page 3
GET /api/v1/media-events?days=1&limit=10&offset=20

If the response returns fewer clusters than limit, you have reached the last page.

Error Codes

Code	HTTP	Meaning
`MISSING_API_KEY`	401	No `Authorization` header
`INVALID_API_KEY`	401	Wrong format or revoked key
`API_ACCESS_DENIED`	403	Plan does not include API access
`RATE_LIMITED`	429	Per-minute RPM limit exceeded. Includes `Retry-After` header.
`QUOTA_EXCEEDED`	429	Monthly QU limit reached
`PLAN_FEATURES_ERROR`	500	Could not load plan features

resp = requests.get(url, headers=headers)

if resp.status_code == 200:
    data = resp.json()
elif resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", 60))
    print(f"Rate limited — retry in {retry_after}s")
elif resp.status_code == 401:
    print("Invalid API key")
elif resp.status_code == 403:
    print("Plan does not include API access")

Reference Codes

Categories (`category` param)

Value	Label
`conflict_security`	Conflict
`politics_governance`	Politics
`crime_justice`	Crime
`economy_business`	Economy
`science_health`	Health
`disaster_emergency`	Disaster
`society_culture`	Society
`technology`	Tech

Scope (`scope` param)

Value	Description
`local`	Event affects a single city/region
`national`	Event affects a single country
`global`	Event involves 2+ countries or international bodies

CAMEO Country Codes (`actor_country` param)

3-letter ISO codes: USA, GBR, CHN, RUS, DEU, FRA, ISR, IRN, SAU, IND

Event Codes (`event_type` param)

Pass the root code prefix: 14=Protest, 18=Assault, 19=Fight, 13=Threaten, 11=Disapprove. See the full CAMEO event code table for all codes.

Article Weight

Measures uniqueness of a news article:

article_weight = 1 / log₂(event_count + 1)

event_count	article_weight	Interpretation
1	1.000	Unique — highest quality
3	0.500	Moderate redundancy
10	0.289	Appears across many events

Cluster articles are sorted by article_weight DESC.

​Overview

API v2

Media Events

Entities

Domains

​Authentication

​Confidence Strictness Spectrum

​Date & Time Parameters

​Response Detail Levels

​/api/v1/media-events

​Summary Response Shape

​Standard Response Shape

​/api/v1/media-events/cluster

​Summary Response Shape

​Standard Response Shape

​/api/v1/entity-geg

​Cluster Deep-Dive (/api/v1/media-events/cluster)

​Parameters

​Filters

​Semantic Search (/api/v1/media-events)

​How it works

​Combining with filters

​Pagination (/api/v1/media-events)

​Error Codes

​Reference Codes

​Categories (category param)

​Scope (scope param)

​CAMEO Country Codes (actor_country param)

​Event Codes (event_type param)

​Article Weight

Overview

Authentication

Confidence Strictness Spectrum

Date & Time Parameters

Response Detail Levels

`/api/v1/media-events`

Summary Response Shape

Standard Response Shape

`/api/v1/media-events/cluster`

Summary Response Shape

Standard Response Shape

`/api/v1/entity-geg`

Cluster Deep-Dive (`/api/v1/media-events/cluster`)

Parameters

Filters

Semantic Search (`/api/v1/media-events`)

How it works

Combining with filters

Pagination (`/api/v1/media-events`)

Error Codes

Reference Codes

Categories (`category` param)

Scope (`scope` param)

CAMEO Country Codes (`actor_country` param)

Event Codes (`event_type` param)

Article Weight