GDELT Cloud — instructions for coding agents
You are building against the GDELT Cloud v2 API. This file is short on purpose: it is the set of rules that stop you from getting a confident, wrong answer at HTTP 200. Everything else is in the docs, and you should read them rather than guess.- Docs: docs.gdeltcloud.com — every page also serves as
.md(append.mdto any URL) - Page index: docs.gdeltcloud.com/llms.txt
- Start here: docs.gdeltcloud.com/quickstart
Connect
There are two different MCP servers, and they are not interchangeable.
Both are JSON-RPC endpoints. Opening either in a browser returns
405 — that is expected, not an
outage. The page explaining the data MCP is /mcp/overview.
--bearer-token-env-var GDELT_API_KEY on Codex (it takes the NAME of an
environment variable, never the key itself) or answer the key prompt on Claude Code. Claude Code,
Codex and Cursor can also install both servers plus eight skills in one command from
github.com/gdelt-cloud/plugins — see
docs.gdeltcloud.com/mcp/plugins.
The docs MCP’s tools are search_gdelt_cloud, query_docs_filesystem_gdelt_cloud and
submit_feedback. query_docs_filesystem_gdelt_cloud is the one to reach for: it can jq the
OpenAPI spec directly, which answers “what parameters does this endpoint take” exactly, where a
natural-language search may not answer it at all. List the names first (about 1 KB for Search
Events), then read only the parameters you need (about 0.5 KB each); every name with its description
is about 20 KB.
REST
Base URLhttps://gdeltcloud.com/api/v2. Auth is one header on every request:
The rules that keep you correct
- Resolve an entity once, then reuse the id.
GET /api/v2/searchis the resolver the rest of the API assumes you called. Never filter by a bare name across endpoints. - Identifier spaces are not interchangeable. A spine
e_…id, awiki:…id, a GEM entity id, a CIK and an LEI are different things, and different endpoints accept different sets. Passing the wrong one usually returns an empty 200, not a 400. Check the identifier reference before chaining two endpoints. - Count before you list, but know that the summary endpoints take a smaller parameter set than
their list siblings. A filter the list endpoint honours may not exist on the summary, and an
unknown parameter is either rejected with
400 UNKNOWN_PARAMon descriptor-backed endpoints or reported inapplied_filters.ignoredon endpoints still using the compatibility contract. Diff the two in the spec before assuming a count and a list describe the same population. bboxaxis order differs by family. Core surfaces take latitude first; maritime takes longitude first. Both orders are numerically valid for most boxes, so a swap cannot 400 — it silently queries a different part of the planet. The per-parameter description in the spec is authoritative.- Geographic filters mean different things. “Events located in X” and “events connected to X”
are separate questions; so are an event at a site and an event at that country’s centroid. Set
country_matchand boundgeo_precisionexplicitly rather than taking the defaults. nullis not0. A null means we did not measure it. Charting it as zero fabricates data.- Check the status and
applied_filterson every response. FixUNKNOWN_PARAMerrors and any non-emptyapplied_filters.ignoredbefore interpreting the data.applied_filters.normalizedlists each parameter the API rewrote to the form it serves (a synonym, alimitor window over the maximum), with what you sent and what was applied: update your request to match. - Bound every query by date. Consistently coded history begins March 2026. A window
entirely before it returns
400 DATE_OUT_OF_COVERAGE; one that starts before it is trimmed to the covered part andmeta.window_adjustmentsays so. - Read the error
code, not just the status.RATE_LIMITEDandQUOTA_EXCEEDEDare both429and call for opposite responses — retry versus stop. See the error reference. - Do not invent parameter values. Every closed vocabulary is published at
/reference/enums, and the 400 for a bad one
carries
details.accepted_values. Observed vocabularies are measurements, not allowlists.
The newer surfaces, briefly
Six more rules for the surfaces added in September 2026. Same shape as the ten above: each one is a way to get a confident, wrong answer at HTTP 200.- Resolve identity first, then reuse the exact id.
GET /api/v2/search?q=…(addcountry=<ISO3>&country_match=strictwhen you know the country; strict alone filters nothing) (MCPunified_entity_search) returns CANDIDATES — inspect them, pick one, and carry that id to/api/v2/activity?entity=,/api/v2/situations?entity=and/api/v2/entities/{id}/offices. Never take the first row because it is first. - Situations: read
meta.situation_sourcebefore anything else.curatedis stored, adjudicated membership with asituation_uid;walkedis an exploration around a Story that no Situation covers yet — the same shape, a weaker claim. Page/stories,/events,/entitiesand/connectionsINDEPENDENTLY: each list has its ownpagination, and each first page returns ascope.versionyou send back asscope_versionon later offsets. On409 SITUATION_SCOPE_CHANGED(a 409 on the member lists is always this), restart that list at offset 0 with no version. POST /api/v2/situationscosts 5 QU for an admitted creation or expansion, 0 QU when it reuses an existing canonical Situation. It needs anIdempotency-Keyheader (8–128 characters of letters, digits and._:-). A timeout is retried with the SAME key and the SAME body; a different body needs a NEW key, or the API answers409 IDEMPOTENCY_CONFLICT.409 AMBIGUOUS_EVENT_SEEDmeans the Event has several supporting Stories — pick one and sendstory_idexplicitly. See docs.gdeltcloud.com/features/situations. Monitor setup, reads, edits and deletes are free over REST and the MCP; a Monitor Preview and Run now cost 1 QU each; saved queries are free./api/v2/activityis observed publication, not source intake. It journals what WE published about identities and records, in committed batches. For anything ongoing usetime_basis=recordedand followpagination.next_cursorwith every other filter unchanged; readmeta.coverageandmeta.exhaustivebefore counting. Exhausting the cursor completes the observed journal at its publication cutoff — it does not mean the upstream register has nothing newer.- Countries have two clocks and two inventories.
basis=reportingcounts distinct served Events by occurrence date and Stories by reporting date (day precision, nohour); the defaultbasis=publicationis the activity journal.facility_countis physical sites,unit_countis registry units — never add them. Economic and resource fundamentals keep their own observation year and vintage; a missing value isnull, not zero.directory=truelists every registered country including quiet ones. - Offices are valid time, and unknown stays unknown.
holds_office=trueon/api/v2/searchfinds office-holders;as_ofon the offices endpoints asks who HELD the office on that date, by the publisher’s own start and end dates, and a holder with no start date is excluded and counted inmeta.undated_office_holders. A holder’s status is what the source asserts — a missing end date does not make someone current. This is actor context, not a PEP or sanctions screen.
403 PROGRAMMATIC_ACCESS_DENIED with
details.reason starter_credit_exhausted; plans are at
gdeltcloud.com/pricing. Do not retry a 403 — read code and stop.
When you are stuck
Ask the docs MCP before guessing. If the docs are wrong or missing something, say so — the docs MCP has asubmit_feedback tool and it reaches a human.
