Quickstart

Four steps from no account to real rows. The first three are free.

Create an account with Google or an email address. Email signups get a confirmation link; it signs you in and brings you back here to step two. No payment method is needed for a Free account.

Create a key

Open API keys, click Create New Key, name it and copy it. Keys look like gdelt_sk_… and are shown once. A key belongs to the workspace it was created in, so check the workspace switcher first if you belong to a team.

export GDELT_API_KEY="gdelt_sk_..."

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

Make your first calls

Your Free account includes 200 starter calls for the REST API and the MCP server. They are a one-time credit and never expire. Run the hello-world call below.

Choose Builder when you need more

Choose Builder for every data endpoint, a monthly Query Unit allowance and three daily Monitors. Checkout shows the price and billing date before you confirm, and the owner can cancel in Subscription. Compare every plan on Pricing.

What Free includes. 50 QU a month in the web app and API Arena, plus the 200 starter calls for the REST API and MCP server. Once those are used, API keys, OAuth, the MCP server and scheduled Monitors need a paid plan, and a call answers 403 PROGRAMMATIC_ACCESS_DENIED with a details.pricing_url to choose one (errors). Ordinary data reads cost 1 QU each; see Pricing for each plan’s allowance.

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. The Python sample needs pip install requests; the TypeScript sample needs Node 18+ as an ES module (top-level await).

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},
)
body = r.json()
if not r.ok:
    # e.g. 403 PROGRAMMATIC_ACCESS_DENIED once the starter calls are used
    raise SystemExit(f"{r.status_code} {body.get('code')}: {body.get('error')} {body.get('details', {}).get('pricing_url', '')}")
for e in body["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 body = await r.json();
if (!r.ok) {
  // e.g. 403 PROGRAMMATIC_ACCESS_DENIED once the starter calls are used
  throw new Error(`${r.status} ${body.code}: ${body.error} ${body.details?.pricing_url ?? ""}`);
}
for (const e of body.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 many of the same filters as its list sibling — days, date, entity, country_match, geo_precision_*, near and radius_km work here. It does not take search; that filter is refused with a 400. See the exact set in the endpoint index and inspect applied_filters on the response.

/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?

The data server answers questions about the world, and it is the one to connect first. It uses your API key or an OAuth sign-in, and its calls draw on the same starter calls and plan allowance as the REST API:

https://mcp.gdeltcloud.com/mcp

The plugin is the fastest path for coding agents: one install wires the data server, the docs server and the workflow skills. Your Connect page shows the same steps with your key filled in.

# inside Claude Code; it prompts for your API key when you enable the plugin
/plugin marketplace add gdelt-cloud/plugins
/plugin install gdelt-cloud@gdelt-cloud

# or the data server alone, signing in with OAuth via /mcp
claude mcp add --transport http gdelt-cloud https://mcp.gdeltcloud.com/mcp

codex plugin marketplace add gdelt-cloud/plugins
codex plugin add gdelt-cloud@gdelt-cloud
export GDELT_API_KEY="gdelt_sk_..."

{
  "mcpServers": {
    "gdelt-cloud": {
      "url": "https://mcp.gdeltcloud.com/mcp",
      "headers": { "Authorization": "Bearer ${env:GDELT_API_KEY}" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "gdelt-api-key", "description": "GDELT Cloud API key", "password": true }
  ],
  "servers": {
    "gdelt-cloud": {
      "type": "http",
      "url": "https://mcp.gdeltcloud.com/mcp",
      "headers": { "Authorization": "Bearer ${input:gdelt-api-key}" }
    }
  }
}

Settings → Connectors → Add custom connector
Paste https://mcp.gdeltcloud.com/mcp
Follow the OAuth sign-in with your GDELT Cloud account
Open a new chat and enable the GDELT Cloud tools

Settings → Connectors → Advanced settings → turn on Developer Mode
Connectors → Create → name "GDELT Cloud", paste https://mcp.gdeltcloud.com/mcp, Auth = OAuth
Authorize with your GDELT Cloud account, then enable GDELT Cloud in a Developer-mode chat

Optionally add the docs server too. It needs no account and returns documentation (every page, parameter and value list), so your assistant can write correct code:

https://docs.gdeltcloud.com/mcp

Connecting only the docs server and then reporting “no events found” is the most common setup mistake. See the MCP overview and Integrations 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 identity, then use each dataset’s supported identifiers across news, tone, awards and 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 or all of history. Without an entity filter, omitting the window uses a rolling 24 hours. With an entity filter, it defaults to 30 calendar days. Other families carry their own defaults, declared in Parameters. Read meta.query_window for the effective bounds and pass days or 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

Monitors

Products

Data

How the data is made

Use cases

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

​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

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