Skip to main content
API v2 is the simplified, recommended interface for generated GDELT Cloud products — clean structured Events, clustered Stories, resolved Entities, energy assets, and geo discovery. v1 remains available for existing integrations (see Legacy v1 API at the bottom of the sidebar). v2 focuses on:
  • Generated structured Events: conflict and cameoplus.
  • Generated clustered Stories.
  • Generated metrics for Events and Stories.
  • Entity discovery and entity-to-Story/Event linking.
  • Entity Tone and Share of Voice beta analytics for cached, evidence-gated media-tone workflows.
  • Global Energy Monitor energy asset and owner search, summaries, maps, and detail records.
v2 does not expose raw GDELT-only fields or legacy tuning knobs such as scope, detail, geo_scope, event_readiness, cluster_certainty, quad_class, or raw total_events.

​
Start here

Concepts & Response Objects

Auth, geography & bounding boxes, the Event/Story/summary response schemas, entity resolution, and ranking.

Taxonomy & Codes

Every controlled value: event families, CAMEO+ domains and codes, Conflict types, story categories, and filter enums.

Cookbook

Field-tested query recipes — monitoring, semantic search, summaries, and drilldowns.

Quickstart

Get an API key and make your first authenticated call.

Authentication

Bearer gdelt_sk_… keys, plans, and access.

MCP server

The same data as agent-callable tools over the Model Context Protocol.

​
Endpoints in the sidebar

Browse the live, interactive endpoint reference in the sidebar — each page has a parameter reference, response schema, and an in-browser playground:
  • Events — search, fetch, and summarize generated structured Events.
  • Stories — search, fetch, list articles, and summarize clustered Stories.
  • Entities — discover people and organizations and resolve names to canonical ids.
  • Unified search — /api/v2/search finds an entity by any name or alias across every universe (news, GEG-Wikipedia, SEC, GEM, screening lists, China dev-finance, Epoch AI) and returns the id the other endpoints take. Open to any authenticated key.
  • Geography — country-scoped admin1 discovery.
  • Energy — Global Energy Monitor asset and owner search, summaries, maps, and detail.
  • Facilities — the unified physical-asset directory (GEM assets + WPI ports + Epoch AI data centers), resolved to spine owners (plan-gated, Analyst+).
  • Filings — SEC EDGAR filings, XBRL financials, and AI-extracted relations (plan-gated: the Corporate & Supply Chain plan and above, can_use_filings).
  • Media Intelligence — Entity Tone (can_use_tone) and Share of Voice (can_use_share_of_voice); social signal remains an admin-only preview.
  • Risk & Screening — restricted-party list catalog, entries, and change feed plus counterparty screening (can_use_screening), and ownership-chain exposure (can_use_exposure).
  • China — China overseas development-finance projects and rollups, AidData GCDF (can_use_china).
  • Government — federal awards and FARA foreign-influence links (can_use_gov).
  • Maritime & Trade — chokepoint transits, dwell episodes, AIS-dark gaps, vessels and carriers, ports, port pulse, and chokepoint watch (can_use_maritime).
  • Markets & Macro — FRED economic series, point-in-time (ALFRED) observations, and releases (can_use_macro).
  • AI & Compute — Epoch AI models, hardware, data centers, companies, and chip sales (can_use_epoch_ai).
  • Briefs — generate source-backed Monitoring Briefs (plan-gated add-on).
Events and Stories accept a languages filter — a comma-separated list of source-language codes (en, zh, ar, es, fr, …) that keeps only items whose linked story has at least one article in those origin (source) languages; multiple codes are OR’d and the alias language is accepted. The Events and Stories list endpoints also accept include_images (default true) to add best-effort representative article image URLs per row (image_url plus top_articles[].image_url). Media Intelligence, Risk & Screening, China, Government, Maritime & Trade, Markets & Macro, and AI & Compute are generally available and plan-gated — if your plan carries the source flag, your key gets the same data these pages demo. A plan without the flag gets a 403 PLAN_REQUIRED naming the missing entitlement, never a silently empty result. Only /api/v2/social (social signal) is still an admin-only internal preview.

​
Authentication

Every request uses a Bearer API key — see Concepts → Authentication:

​
Entity Tone & Share of Voice (beta)

Entity Tone is an opt-in, evidence-gated beta surface for media tone toward a resolved entity — not polling data or a direct measure of public opinion. Missing tone rows mean not_available or insufficient_entity_evidence, not neutral. Evidence is drawn from clustered news plus supplementary social signal (Bluesky / AT Protocol) where available, with a news-vs-social split so you can see how press-driven a read is. tone_score is returned on a -100..100 scale; risk_score on 0..100. Share of Voice is denominator-explicit: /api/v2/share-of-voice requires entities, start_date, end_date, and at least one denominator-defining filter (query, topic, category, country, region, languages, or source_set). Requests without a denominator return DENOMINATOR_REQUIRED so callers cannot report a percentage without a defined media space. topic is the literal story-label denominator (the exact label bounds the media space); query is the semantic, embedding-based denominator (opt-in and slower — it defines the media space by similarity rather than a literal label). Responses include a plot-ready timeline with zero-filled buckets and per-point story_share, article_share, weighted_share, and delta_from_previous_bucket. Add include_tone=true to join cached tone aggregates, languages (e.g. ar,zh,en) to compare coverage across language spheres, and include_drivers=true for citable per-bucket drilldowns.
Entity Tone and Share of Voice are beta — methodology and response shape may still change — but they are generally available, not admin-only. Entity Tone requires can_use_tone (the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans); Share of Voice requires can_use_share_of_voice (Media Intelligence, Geopolitical Intelligence, and Global Intelligence). Find them under Media Intelligence in the sidebar.