GDELT Cloud Docs — Global Event Data API & MCP

We read the world’s news and produce a structured event database from it: events coded into a taxonomy, stories clustered from the articles behind them, entities resolved to a single identity across every surface, and tone scored on how each of them is covered. Query it over REST, or point an agent at the MCP server.

import os, requests

r = requests.get(
    "https://gdeltcloud.com/api/v2/events",
    headers={"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"},
    params={"country": "Nigeria", "days": 7, "limit": 5},
)
for e in r.json()["data"]:
    print(e["event_date"], e["category"], "—", e["title"])

Quickstart

A working call in two minutes, plus the docs MCP server.

API reference

Every endpoint, parameter and value.

What you can ask it


What happened	`/events` — coded incidents with actors, geography, taxonomy and metrics
What is being said	`/stories` — article clusters with the source coverage behind them
How much, where, trending how	`/events/summary`, `/stories/summary` — counts grouped by date, place or category
Who is involved	`/search` then `/entities` — resolve a name once, reuse the id everywhere
How they are being covered	`/entities/{id}/tone`, `/share-of-voice` — press tone and coverage share over time
What they own or are exposed to	`/facilities`, `/gov/awards`, `/filings`, `/exposure` — the same entity id, other surfaces

The one idea worth knowing

Resolve a name to an id once, then never resolve it again. Every surface above takes the same entity id, so one call to /search joins news, tone, awards, filings, physical assets and ownership exposure. Filtering by name string instead silently matches a different subset on each — with no endpoint returning an error.

Track an entity across every surface

Resolve a name to an id once, then reuse that id on news, tone, awards and physical assets.

What is ours and what we ingest

Core is what we produce — events, stories, entities, tone. We code every event under our own taxonomy from the raw article stream; we do not resell anyone’s event data. Open Feeds are public registries we ingest and resolve onto the same entity spine — SEC filings, GLEIF, USAspending, FRED, Global Energy Monitor, Epoch AI and more. The value we add is the fusion.

Data catalog

Every dataset, its licence, its coverage window, and what it does not cover.

Consistently coded history begins in March 2026. Earlier dates return a near-empty result that reads like a bug and is not — history is being extended backwards.

Start here

Use cases

Monitors

Products

Data

How the data is made

GDELT Cloud

Quickstart

API reference

What you can ask it

The one idea worth knowing

Track an entity across every surface

What is ours and what we ingest

Data catalog

Quickstart

API reference

​What you can ask it

​The one idea worth knowing

Track an entity across every surface

​What is ours and what we ingest

Data catalog

What you can ask it

The one idea worth knowing

What is ours and what we ingest