Skip to main content
You do not need to write code to use GDELT Cloud. Connect the MCP server to Claude, ChatGPT or your own agent, and ask in plain language — the model picks the endpoints, and every claim comes back with the articles behind it. This page walks one real question end to end. The numbers in it are what the API actually returned on 2026-08-26.
1

Connect (about two minutes)

Add the server URL to your client and authenticate with your API key. Setup is three lines of config per client and is written out in Integrations.
You are connected when the model can list the GDELT Cloud tools. If it lists documentation tools instead, you connected the docs server — see the MCP overview for both.
2

Start wide, not narrow

“What’s been happening in Nigeria over the past two weeks?”
Ask the broad version first. The model calls a summary endpoint, which returns counts grouped by date, geography or category — the shape of the period rather than a list of rows. Fifteen buckets came back; the top of it looked like this:This is the step people skip, and skipping it is the single biggest source of wrong answers. Go straight to a narrow filtered query and an empty result looks like “nothing happened” when it actually means “that combination of filters matched nothing.”It also reframes the question. Of the five rows above, the biggest bucket has the second-lowest average significance and the smallest has the highest — 33 events against 776. Volume and importance are different questions, and the summary is the only place you see both at once. Read the counts alongside the averages: further down that same response, a two-event bucket posted the highest average of all fifteen, which is a small sample and not a finding.
3

Drill into what the summary surfaced

“Show me the most significant infrastructure events, with sources.”
Now the narrowing is grounded in something you have seen. The model filters to a bucket that actually carried volume and ranks by significance — the blended score the product sorts by, designed to compare events across domains rather than within one:
4

Check the evidence

“What are the underlying articles for the first one?”
Every event traces back to the stories it was coded from, and every story to its source articles with URLs and publication dates. That first row resolves to four stories, the largest carrying five articles:
Nigeria’s federal government adds 208MW to Lagos grid, upgrades Ijora and Apapa substations — 5 articles, 2026-08-18
Ask for this every time. An event is our reading of a cluster of coverage; the articles are what that reading was based on, and they are how you tell a well-supported event from a thin one.Two signals worth checking: how many articles back the story, and whether they are independent outlets or one wire story republished.
5

Widen to the entity

“Does Dangote have US federal contracts or sanctions exposure?”
Once an entity is named, the same resolved identity reaches government awards, corporate filings, ownership-chain exposure and physical assets. The model resolves the name once and reuses that identity everywhere, so the answer does not silently cover only the surfaces where the name happened to be spelled the same way.The resolver also says up front which surfaces carry the entity. Dangote Group resolves to a single id carrying news and Wikipedia coverage and nothing on the government surface, and the awards endpoint says so in its own words rather than returning a bare empty list:
The USAspending dataset is available, but no federal awards matched this subject in the ingested window.
That is a real answer about the corpus, not a failed lookup — and the difference is one a model can only report if the API states it.

​
What to trust, and how far

When coverage was not found, the API returns null rather than 0. If a model reports “no negative coverage,” check whether that means measured and none or not measured. The distinction is preserved in the data specifically so it can be preserved in the answer.
It is scored across news articles. A country with little coverage has little tone data — that is a statement about the press, not about the country.
Coverage starts partway through 2026 and is being backfilled; before that it is thin enough to be misleading. A query reaching further back returns a near-empty result that looks like a bug. The window is in Coverage, and the exact span and cadence per dataset are in the data catalog.
Each event metric has a published list of what it explicitly does not measure — the most common misreading is treating market sensitivity as a severity score. See worked examples for two real events scored by hand.

​
Next

Connect your client

Claude, Claude Code, ChatGPT, Codex, LangChain.

The same flow in HTTP

Summarize, drill, fetch articles, fan out — as four API calls.

Data catalog

What is ours, what we ingest, and what each source does not cover.