GDELT Cloud Docs — Global Event Data API & MCP

Get a key

Create one at gdeltcloud.com/api-keys. Keys look like gdelt_sk_… and are shown once.

export GDELT_API_KEY="gdelt_sk_..."

That is the whole authentication story: a bearer token on every request.

A new account starts a 7-day evaluation with 1,000 QU, the full UI, REST API and MCP access, and up to three daily email Monitors (one 7-day extension on request). Bulk downloads remain paid-only. When the evaluation ends, Free keeps the web app, API Arena, saved Monitor settings and previews with 50 QU a month. API keys, OAuth, the MCP server and scheduled Monitor execution require active access; Monitor webhooks and bulk downloads remain paid-only. A key without active access answers 403 PROGRAMMATIC_ACCESS_DENIED (errors). Eligible existing personal Free workspaces can claim a one-time 500 QU grant, valid 7 days from activation.

When adding filters, pick values from the value reference and Event taxonomy. Use explicit dates for repeatable queries; the effective request window is in meta.query_window, and available history is in meta.coverage. When part of a valid Event or Story date range has not published, the API returns the safely published rows with coverage.served_dates, lists withheld partitions and reasons in coverage.missing_dates, and sets coverage.window_complete to false. It returns a retryable snapshot error only when no requested partition can safely answer.

Hello, world

No filters. The most significant event in the endpoint’s default window:

curl "https://gdeltcloud.com/api/v2/events?limit=1" \
  -H "Authorization: Bearer $GDELT_API_KEY"

import os, requests

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

const r = await fetch("https://gdeltcloud.com/api/v2/events?limit=1", {
  headers: { Authorization: `Bearer ${process.env.GDELT_API_KEY}` },
});
const { data } = await r.json();
for (const e of data) {
  console.log(e.event_date, e.category, e.title, "→", e.geo.country);
}

A real response, trimmed to the fields worth meeting first:

{
  "success": true,
  "data": [
    {
      "id": "cameoplus_3d9c8c58a6f504f0",
      "family": "cameoplus",
      "title": "Iran keeps Strait of Hormuz closed as southern route shuts",
      "event_date": "2026-08-26",
      "category": "INFRASTRUCTURE",
      "subcategory": "IN02",
      "subcategory_label": "Transport Disruption",
      "geo": {
        "country": "Iran",
        "region": "Middle East",
        "location": "Strait of Hormuz",
        "latitude": 26.5667,
        "longitude": 56.25
      },
      "actors": [
        { "name": "Iranian Armed Forces", "country": "Iran", "role": "source" },
        { "name": "Commercial vessels", "country": null, "role": "target" }
      ],
      "metrics": {
        "significance": 0.8769,
        "magnitude": 8,
        "article_count": 162,
        "evidence_source_count": 16,
        "confidence": 0.9
      },
      "fatalities": null,
      "story_refs": [
        {
          "id": "26826d1cf2e2",
          "title": "Iran and Oman hold talks to manage Strait of Hormuz in Tehran",
          "article_count": 162
        }
      ]
    }
  ],
  "pagination": { "limit": 1, "cursor": null, "next_cursor": "s.20260826185024.1" },
  "sort": "significance",
  "applied_filters": { "country": [], "category": [], "search": null, "ignored": {} },
  "meta": {
    "row_source": "settled",
    "coverage": { "start": "2026-03-01", "end": "2026-08-26" }
  }
}

That is the whole product in one row. An event is a coded claim — a date, a place, actors, a taxonomy code and metrics — and story_refs points at the clustered coverage it was read from. The 162 articles behind it are one event, not 162.

Every response on this page was returned on 2026-08-26 and is reproduced as returned, trimmed to the fields under discussion. A live row carries more — metric sub-factors with their stated reasons, entity references, a language breakdown and the top source articles — and the values move with the news.

Then, in the workspace

In the signed-in workspace, investigate a company, follow a country or retrieve coded Events. Use this data shows the actual request and response; copy its code or open the supported scope in the API Arena. Confirm a company’s identity before following its reporting. Profile overview panels retain their labelled recent windows; the Events and Stories links carry your chosen reporting dates. Semantic search retrieves a bounded similarity candidate pool. Changing page size can change that pool, and deep pagination is not an exhaustive, stable export of every matching record. For extraction jobs, use structured filters and the documented dataset download scope. Inspect the source articles: a Story may match a country through a linked Event while its representative geography describes another location. Monitor this carries compatible filters into a draft. Preview shows 7 or 30 days of evidence; scheduled matching follows newly committed records since the previous successful checkpoint. The original discovery dates remain in the saved request for context. It does not save a Monitor or enable deliveries automatically. If a source needs additional access, its plan link retains your results and shows current catalog options. Return to the same work after reviewing access. The Data & coverage page is the source inventory; it distinguishes measured holdings from planned coverage and available API access from published bulk files.

The same shape, for narratives

/events answers what happened. /stories answers what is being said — the article clusters underneath.

curl "https://gdeltcloud.com/api/v2/stories?limit=1" \
  -H "Authorization: Bearer $GDELT_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "743d7e77540a",
      "title": "Nepal Home Minister urges residents in riverbank areas to stay safe",
      "story_date": "2026-08-26",
      "category": "Environment",
      "geo": { "country": "Nepal", "region": "South Asia", "location": "Kathmandu" },
      "metrics": {
        "significance": 0.6618,
        "article_count": 443,
        "linked_event_count": 1,
        "max_linked_event_significance": 0.3139
      },
      "has_events": true,
      "linked_events": [
        {
          "id": "cameoplus_fa603ddb316711fb",
          "title": "Nepal President Paudel urges nationwide rescue effort"
        }
      ],
      "top_articles": [
        {
          "url": "https://aljazeera.com/gallery/2026/8/26/photos-avalanche-floods-kill-eight-hundreds-missing-in-nepals-himalayas?traffic_source=rss",
          "title": "Photos: Avalanche floods kill eight, hundreds missing in Nepal’s Himalayas",
          "domain": "aljazeera.com"
        }
      ]
    }
  ],
  "sort": "significance"
}

443 articles, one story, one linked event. That collapse is why an article count and an event count answer different questions — the nouns are in Concepts.

Count before you list

This is the step that saves the most time. The summary endpoints return counts grouped by date, geography or category — the shape of a period — so you can see where the volume actually is before committing to a filter.

curl -G "https://gdeltcloud.com/api/v2/events/summary" \
  --data-urlencode "country=Nigeria" \
  --data-urlencode "days=30" \
  --data-urlencode "group_by=category" \
  -H "Authorization: Bearer $GDELT_API_KEY"

import os, requests

r = requests.get(
    "https://gdeltcloud.com/api/v2/events/summary",
    headers={"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"},
    params={"country": "Nigeria", "days": 30, "group_by": "category"},
)
for bucket in r.json()["data"]:
    print(f"{bucket['key']:<32} {bucket['event_count']}")

const q = new URLSearchParams({ country: "Nigeria", days: "30", group_by: "category" });
const r = await fetch(`https://gdeltcloud.com/api/v2/events/summary?${q}`, {
  headers: { Authorization: `Bearer ${process.env.GDELT_API_KEY}` },
});
const { data } = await r.json();
data.forEach((b) => console.log(b.key.padEnd(32), b.event_count));

Seventeen buckets came back; the first six, with the noisiest fields dropped:

{
  "group_by": "category",
  "data": [
    { "key": "POLITICAL", "event_count": 1786, "article_count": 5669, "avg_significance": 0.2829 },
    { "key": "CRIME", "event_count": 363, "article_count": 1042, "avg_significance": 0.256 },
    { "key": "INFRASTRUCTURE", "event_count": 93, "article_count": 186, "avg_significance": 0.3691 },
    { "key": "Strategic developments", "event_count": 75, "article_count": 223, "avg_significance": 0.1924 },
    { "key": "Violence against civilians", "event_count": 72, "article_count": 415, "avg_significance": 0.4997 },
    { "key": "ECONOMIC", "event_count": 69, "article_count": 144, "avg_significance": 0.3394 }
  ]
}

Read it before you filter. The first bucket holds 1,786 events and the fifth holds 72 — and the fifth is the one carrying the highest average significance of the six. Volume and importance are different questions, and a list query aimed at the biggest bucket would have walked past the answer.

A summary endpoint takes almost the same filters as its list sibling — days, date, entity, country_match and geo_precision_* all work here. The handful it does not take are listed in the endpoint index, and it tells you about them: near/lat/lon/radius_km come back under applied_filters.ignored, and search is refused with a 400.

/stories/summary does the same for narrative clusters. Now filter the list endpoint down to the buckets that actually carried volume — and read applied_filters on both calls to confirm the two describe the same population.

Add filters one at a time. Stacking four on the first call is the most common way to get an empty result and conclude the data is missing, when it is really the AND of your filters. Check applied_filters in the response — it echoes exactly what the server used.

Prefer to work through an agent?

Two MCP servers, and connecting the wrong one is the most common setup mistake. The docs server is unauthenticated and returns documentation — every page, parameter and value list, so your assistant can write correct code without copy-pasting:

https://docs.gdeltcloud.com/mcp

claude mcp add --transport http gdelt-docs https://docs.gdeltcloud.com/mcp

codex mcp add gdelt-docs --url https://docs.gdeltcloud.com/mcp

{
  "mcpServers": {
    "gdelt-docs": {
      "type": "http",
      "url": "https://docs.gdeltcloud.com/mcp"
    }
  }
}

Settings → Connectors → Add custom connector
https://docs.gdeltcloud.com/mcp

Claude Code, Codex and Cursor can install both servers plus eight skills in one command instead — see Plugins. The data server is a different URL, requires your API key or an OAuth sign-in, and is the one that answers questions about the world rather than about this site:

https://gdelt-cloud-mcp.fastmcp.app/mcp

Connecting only the docs server and then reporting “no events found” is the mistake — see the MCP overview for both.

https://docs.gdeltcloud.com/mcp is a JSON-RPC endpoint, not a page — opening it in a browser returns 405, which is expected. The page describing the MCP surface is /mcp/overview.

Then pick your path

I'm building something

Resolve an entity once, then reuse that id across news, tone, awards and physical assets.

I'm answering a question

Work in plain language through the MCP server, with citations.

Two things that will save you time

Event and story lists do not default to a week, and they do not default to all of history. Omitting the window bounds the request to the last two days — today and yesterday. Other families carry their own default, declared on each days parameter in Parameters. Pass days or an explicit date_start/date_end whenever the window matters to your answer. Coverage does not run all the way back. A query reaching before the coded window returns a near-empty result that looks like a bug and is not. The window, and what it means for a query, is in Coverage; per-dataset windows are in the data catalog.

Start here

Use cases

Monitors

Products

Data

How the data is made

Quickstart

Get a key

Hello, world

Then, in the workspace

The same shape, for narratives

Count before you list

Prefer to work through an agent?

Then pick your path

I'm building something

I'm answering a question

Two things that will save you time

​Get a key

​Hello, world

​Then, in the workspace

​The same shape, for narratives

​Count before you list

​Prefer to work through an agent?

​Then pick your path

I'm building something

I'm answering a question

​Two things that will save you time

Get a key

Hello, world

Then, in the workspace

The same shape, for narratives

Count before you list

Prefer to work through an agent?

Then pick your path

Two things that will save you time