GDELT Cloud Documentation - Global News Event Analytics API

Overview

The GDELT Cloud Developer API (/api/v1/*) provides programmatic access to GDELT event data starting from January 2025, with historical coverage expanding over time and new data updated hourly. Use it to fetch media event clusters, entity profiles, and news domain data from your own applications and scripts.

Media Events

Top news stories clustered from articles, filterable by category, country, 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 are available on Analyst and Professional plans only.

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

Plan Limits

Plan	Monthly QU	RPM	API Access
Free	100	—	✗
Scout	1,000	—	✗
Analyst	10,000	30	✓
Professional	Unlimited	120	✓

QU = Query Units consumed per request. RPM = requests per minute.

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 embedded into a 768-dimensional vector using OpenAI text-embedding-3-small
ClickHouse performs an ANN (Approximate Nearest Neighbor) search against pre-computed article embeddings using an HNSW index
Results are grouped by cluster and ranked by best match distance (lowest = most similar)

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.

API Endpoints

API Reference

Overview

Media Events

Entities

Domains

Authentication

Plan Limits

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

Error Codes

Reference Codes

Categories (`category` param)

Scope (`scope` param)

CAMEO Country Codes (`actor_country` param)

Event Codes (`event_type` param)

Article Weight

API Endpoints

​Overview

Media Events

Entities

Domains

​Authentication

​Plan Limits

​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

Plan Limits

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