Skip to main content

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.

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.
For the data MCP, add --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 URL https://gdeltcloud.com/api/v2. Auth is one header on every request:
Keys are created at gdeltcloud.com/api-keys and shown once.

The rules that keep you correct

  1. Resolve an entity once, then reuse the id. GET /api/v2/search is the resolver the rest of the API assumes you called. Never filter by a bare name across endpoints.
  2. Identifier spaces are not interchangeable. A spine e_… id, a wiki:… 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.
  3. 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_PARAM on descriptor-backed endpoints or reported in applied_filters.ignored on endpoints still using the compatibility contract. Diff the two in the spec before assuming a count and a list describe the same population.
  4. bbox axis 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.
  5. 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_match and bound geo_precision explicitly rather than taking the defaults.
  6. null is not 0. A null means we did not measure it. Charting it as zero fabricates data.
  7. Check the status and applied_filters on every response. Fix UNKNOWN_PARAM errors and any non-empty applied_filters.ignored before interpreting the data. applied_filters.normalized lists each parameter the API rewrote to the form it serves (a synonym, a limit or window over the maximum), with what you sent and what was applied: update your request to match.
  8. 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 and meta.window_adjustment says so.
  9. Read the error code, not just the status. RATE_LIMITED and QUOTA_EXCEEDED are both 429 and call for opposite responses — retry versus stop. See the error reference.
  10. 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.
  1. Resolve identity first, then reuse the exact id. GET /api/v2/search?q=… (add country=<ISO3>&country_match=strict when you know the country; strict alone filters nothing) (MCP unified_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.
  2. Situations: read meta.situation_source before anything else. curated is stored, adjudicated membership with a situation_uid; walked is an exploration around a Story that no Situation covers yet — the same shape, a weaker claim. Page /stories, /events, /entities and /connections INDEPENDENTLY: each list has its own pagination, and each first page returns a scope.version you send back as scope_version on later offsets. On 409 SITUATION_SCOPE_CHANGED (a 409 on the member lists is always this), restart that list at offset 0 with no version.
  3. POST /api/v2/situations costs 5 QU for an admitted creation or expansion, 0 QU when it reuses an existing canonical Situation. It needs an Idempotency-Key header (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 answers 409 IDEMPOTENCY_CONFLICT. 409 AMBIGUOUS_EVENT_SEED means the Event has several supporting Stories — pick one and send story_id explicitly. 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.
  4. /api/v2/activity is observed publication, not source intake. It journals what WE published about identities and records, in committed batches. For anything ongoing use time_basis=recorded and follow pagination.next_cursor with every other filter unchanged; read meta.coverage and meta.exhaustive before counting. Exhausting the cursor completes the observed journal at its publication cutoff — it does not mean the upstream register has nothing newer.
  5. Countries have two clocks and two inventories. basis=reporting counts distinct served Events by occurrence date and Stories by reporting date (day precision, no hour); the default basis=publication is the activity journal. facility_count is physical sites, unit_count is registry units — never add them. Economic and resource fundamentals keep their own observation year and vintage; a missing value is null, not zero. directory=true lists every registered country including quiet ones.
  6. Offices are valid time, and unknown stays unknown. holds_office=true on /api/v2/search finds office-holders; as_of on 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 in meta.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.
One access rule alongside them: a Free account’s API keys and MCP access stop when its one-time starter calls are used. After that, a key answers 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 a submit_feedback tool and it reaches a human.