# GDELT Cloud

- [GDELT Cloud — geopolitical events and entity data API](https://docs.gdeltcloud.com/index.md): Query structured geopolitical events, clustered news stories, linked people, organizations and places through the GDELT Cloud REST API and MCP server.
- [Quickstart](https://docs.gdeltcloud.com/quickstart.md): One real call, one real response, in about two minutes.
- [API keys](https://docs.gdeltcloud.com/api-keys.md): Generate and manage API keys for programmatic access to the Developer API
- [Concepts](https://docs.gdeltcloud.com/concepts.md): The six nouns the whole API is built from, and the conventions every endpoint shares.
- [Monitors](https://docs.gdeltcloud.com/guides/monitors.md): Turn one API question into a scheduled check, delivered by email or signed webhook.
- [Monitor webhooks](https://docs.gdeltcloud.com/guides/monitor-webhooks.md): Configure, verify and safely consume signed Monitor deliveries.
- [Situations](https://docs.gdeltcloud.com/features/situations.md): Follow a maintained collection of Stories and coded Events about one occurrence or developing thread, inspect its evidence, and use the same result through the API.
- [Data catalog](https://docs.gdeltcloud.com/data/catalog.md): Every dataset behind the API — what we produce, what we ingest, the licence, the coverage window, and the known gap.
- [Facilities, minerals and AI compute](https://docs.gdeltcloud.com/data/facilities-and-resources.md): Find physical assets, inspect contributing sources and participants, and keep country mineral statistics separate from facility and compute capacity.
- [Restricted-party sources and ownership exposure](https://docs.gdeltcloud.com/data/risk-and-screening.md): Discover current publisher lists, screen counterparties, and inspect ownership-chain risk without treating every listing as a sanction.
- [As-of claims and coding latency](https://docs.gdeltcloud.com/data/as-of-and-latency.md): What you can honestly claim about when we knew something, why events are coded after the day they happened, and how to build a point-in-time view for backtesting.
- [Political offices and persons](https://docs.gdeltcloud.com/data/political-offices.md): Public offices and who has held them, national and subnational, from official rosters and Wikidata — with a valid-time as_of, a deliberately minimal person record, and no claim to be a screening product.
- [Bulk events schema](https://docs.gdeltcloud.com/data/bulk-events-schema.md): Every column in a downloaded event file, in Parquet and CSV.
- [Bulk stories schema](https://docs.gdeltcloud.com/data/bulk-stories-schema.md): Every column in a downloaded story file, in Parquet and CSV.
- [Event Coding: Conflict & CAMEO+](https://docs.gdeltcloud.com/features/event-coding.md): How GDELT Cloud generates structured Conflict and CAMEO+ Events from Story clusters.
- [Conflict Data](https://docs.gdeltcloud.com/features/conflict-data.md): AI-coded political violence and protest events using the ACLED methodology
- [Atlas Overview](https://docs.gdeltcloud.com/features/atlas.md): Atlas is GDELT Cloud's family of geopolitical indices — a glass-box way to ask how tense a place is, what condition it is in, how capable it is, and where it is heading, computed entirely from our own coded events, narratives, and resolved entities.
- [Atlas methodology](https://docs.gdeltcloud.com/features/atlas-methodology.md): How the two live Atlas indices are computed — GPR against a place's own baseline, Posture against fixed reference points.
- [Worked examples](https://docs.gdeltcloud.com/metrics/worked-examples.md): Two real events, scored by hand, so you can check our arithmetic against the published definitions.
- [Limits and error bars](https://docs.gdeltcloud.com/metrics/limits.md): What the four metrics do not claim, and the measured noise floor on each scale.
- [Track an entity across datasets](https://docs.gdeltcloud.com/guides/for-developers.md): Resolve an identity, then use each dataset's documented identifiers to connect news, tone, awards and physical assets.
- [Answer a question with MCP](https://docs.gdeltcloud.com/guides/for-analysts.md): The analyst path: connect once, then work in plain language with citations you can check.
- [Recipes](https://docs.gdeltcloud.com/guides/recipes.md): Short, verified queries for the shapes people ask for most — copy one and change the filters.
- [Search Events](https://docs.gdeltcloud.com/api-reference/events/search-events.md): Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. Finish pagination.next_cursor within each fixed window before starting the next chunk without a cursor. Without an explicit window, entity filters default to 30 days…
- [Get Event](https://docs.gdeltcloud.com/api-reference/events/get-event.md): Fetch one known structured Event by ID.
- [Get Event Stories](https://docs.gdeltcloud.com/api-reference/events/get-event-stories.md): Stored, addressable Stories connected to this Event through primary or rehomed links. Incident-member IDs resolve to the canonical Event. Published serving edges select membership; Story titles, dates and article counts come from the published Story snapshot. The serving edge does not yet project re…
- [Summarize Events](https://docs.gdeltcloud.com/api-reference/events/summarize-events.md): Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other…
- [Search Stories](https://docs.gdeltcloud.com/api-reference/stories/search-stories.md): Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. Finish pagination.next_cursor within each fixed window before starting the next chunk without a cursor. Without an explicit window, entity filters default to 30 days…
- [Get Story](https://docs.gdeltcloud.com/api-reference/stories/get-story.md): Fetch one known Story by ID with linked Events, linked Entities, metrics, public URL, normalized geo, and top 3 inline articles.
- [Get Story Articles](https://docs.gdeltcloud.com/api-reference/stories/get-story-articles.md): Canonical-URL-deduplicated article evidence with source language and provenance-backed publisher country.
- [Summarize Stories](https://docs.gdeltcloud.com/api-reference/stories/summarize-stories.md): Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other…
- [List Situations](https://docs.gdeltcloud.com/api-reference/situations/list-situations.md): Discover stored Situations by title, current servable span overlap and volume counts, or member-linked coded Event location/category. Event facets require a reporting window of at most 30 days and match the same Event; they do not establish a primary country or category. Directory filtering, orderin…
- [Create or expand a shared Situation](https://docs.gdeltcloud.com/api-reference/situations/create-or-expand-a-shared-situation.md): Accepts a strict JSON body containing story_id or event_uid, optional direction (back or forward), and optional situation_uid for explicit expansion. An Event with several supporting Stories returns 409 and requires story_id selection. An existing canonical Situation is reused for 0 QU when situatio…
- [Get a Situation](https://docs.gdeltcloud.com/api-reference/situations/get-a-situation.md): Every Story and Event belonging to one real-world occurrence. The path accepts EITHER a `situation_uid` (`sit_…`) or any member Story id, and both return the same occurrence — a Story resolves to its primary Situation. A `situation_uid` is minted and content-independent, so it never changes; a Situa…
- [List all linked entities in a stored Situation](https://docs.gdeltcloud.com/api-reference/situations/list-all-linked-entities-in-a-stored-situation.md): Paginated canonical entities across full servable stored membership, independently of the detail endpoint’s 40-entity or 200/250-member view. Identity merging precedes type filtering and pagination. summary.entity_count and by_type cover the whole requested scope; pagination.total covers the type fi…
- [List a Situation's stories](https://docs.gdeltcloud.com/api-reference/situations/list-a-situations-stories.md): Independently paginated stories over current servable membership. Summary and pagination totals cover all matching members, never a graph sample. Article counts sum member Story counts, not unique URLs. Date filters select member reporting dates; Event occurrence dates remain separate.
- [List a Situation's events](https://docs.gdeltcloud.com/api-reference/situations/list-a-situations-events.md): Independently paginated events over current servable membership. Summary and pagination totals cover all matching members, never a graph sample. Article counts sum member Story counts, not unique URLs. Date filters select member reporting dates; Event occurrence dates remain separate. Event facts ar…
- [List Situation membership connections chronologically](https://docs.gdeltcloud.com/api-reference/situations/list-situation-membership-connections-chronologically.md): Every servable membership connection, independently paginated and grouped by reporting day. Includes the stored membership relationship, first-observed timestamp, linking Story and recorded adjudication evidence. This is membership provenance, not a causal assertion or a sampled pair graph.
- [Read a retained Situation brief](https://docs.gdeltcloud.com/api-reference/situations/read-a-retained-situation-brief.md): Edition-bound as-of explanation, salient Events and actors, supported relationships, time-step traversal, full-scope statistics, frozen citations, previews and detail links. New editions do not forecast. Structure adds typed graph nodes and edges; context adds source-gated existing context. No model…
- [List retained Situation editions](https://docs.gdeltcloud.com/api-reference/situations/list-retained-situation-editions.md): Immutable manifests newest first, including stable daily references. Capture time, reporting cutoff and publication time are distinct. Retention begins at rollout; older clipped snapshots are not reconstructed.
- [Discover entities in reporting](https://docs.gdeltcloud.com/api-reference/entities/discover-entities-in-reporting.md): Discover people, organizations and places appearing in reporting. For initial identity lookup, use `/api/v2/search?q=…`, select a candidate, then reuse its ID on the destination endpoint. This endpoint returns coverage metrics over the requested window. `search=` resolves a NAME across every entity…
- [Get Entity](https://docs.gdeltcloud.com/api-reference/entities/get-entity.md): Fetch one Entity profile with linked Stories and Events. include_tone=true attaches media-tone coverage with explicit unavailable status. include_registry=true overlays entitled registry sections and corporate_context: bounded, typed parent/child relationships and separately attributed parent SEC id…
- [Corporate hierarchy for a resolved entity](https://docs.gdeltcloud.com/api-reference/entities/corporate-hierarchy-for-a-resolved-entity.md): An entity's corporate hierarchy resolved through our spine: `direct_parent`, `ultimate_parent`, `parent_assertions`, `parent_chain`, `children` and `child_count`. Accepts the same identifiers as the rest of the API — a name, an `e_` id, a `wiki:` id or a wikipedia_url — and additionally a bare 20-ch…
- [Entity tone (by entity)](https://docs.gdeltcloud.com/api-reference/entities/entity-tone-by-entity.md): Media tone toward a specific entity over a date window, with optional cited evidence. Requires a plan with Entity media tone access (`can_use_tone`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Entity Dossier — the statecraft timeline](https://docs.gdeltcloud.com/api-reference/entities/entity-dossier-—-the-statecraft-timeline.md): One Actor in, one time-ordered, cited chronology out: public-list membership evidence as a change log (`list_added` / `list_removed`), public offices held (`office_start` / `office_end`), FARA foreign-agent registrations, federal awards and the coded event stream — fusing news and registry records w…
- [Read publication activity](https://docs.gdeltcloud.com/api-reference/entities/read-publication-activity.md): A change feed of records GDELT Cloud published to its API: Events, Stories, entities and other entitled sources. Use it to watch additions, updates and removals; it is not a customer API-request log, and its dates are not Event occurrence dates. Paginated observed evidence of successful serving/refe…
- [Share of Voice](https://docs.gdeltcloud.com/api-reference/entities/share-of-voice.md): Compare an entity’s share of canonical settled Story records within one explicit news denominator. Story membership and entity references come from the Core serving tables; unsupported article-level and upstream-salience weighting are not published.
- [Unified cross-source entity search](https://docs.gdeltcloud.com/api-reference/unified-search/unified-cross-source-entity-search.md): Resolve a name, alias, or acronym into ranked entity candidates before creating a Monitor or calling an entity-conditioned endpoint. `q` is the canonical query parameter; choose a result and reuse its entity_id for reporting. Facility candidates retain facility_id for facility context; ownership and…
- [Entity tone](https://docs.gdeltcloud.com/api-reference/media-intelligence/entity-tone.md): Entity-conditioned media tone, risk, and confidence over a window, with cited evidence. Resolve the entity first with /api/v2/search. Requires a plan with Entity media tone access (`can_use_tone`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [List tone runs](https://docs.gdeltcloud.com/api-reference/media-intelligence/list-tone-runs.md): List entity-tone scoring runs. Requires a plan with Entity media tone access (`can_use_tone`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Trigger a tone run](https://docs.gdeltcloud.com/api-reference/media-intelligence/trigger-a-tone-run.md): Queue an on-demand entity-tone scoring run for an entity/topic. Requires a plan with Entity media tone access (`can_use_tone`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Tone run status](https://docs.gdeltcloud.com/api-reference/media-intelligence/tone-run-status.md): Status + result of a queued entity-tone run. Requires a plan with Entity media tone access (`can_use_tone`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Search Facilities](https://docs.gdeltcloud.com/api-reference/facilities/search-facilities.md): Physical-asset directory combining GEM energy and heavy industry, ports, Epoch and ComputeAtlas data centers, USGS mineral facilities, Climate TRACE and EEA factories. Independently reviewed cross-source identities share a canonical site; source observations, units and unresolved ownership remain ex…
- [Get Facility](https://docs.gdeltcloud.com/api-reference/facilities/get-facility.md): Returns a canonical physical site with unit count, unit identifiers and status breakdown. A legacy registry-unit id resolves to the same parent site.
- [Facility context](https://docs.gdeltcloud.com/api-reference/facilities/facility-context.md): A facility fused with its OWNER's media coverage, plus optional nearby reporting and government exposure. Returns `owner_events` — events about the owner, NOT events located at the site. When the owner cannot be resolved or cannot be bridged to the news layer, the arrays are `null` rather than empty…
- [List Facility registry units](https://docs.gdeltcloud.com/api-reference/facilities/list-facility-registry-units.md): Lists the source registry units belonging to a canonical physical site. A canonical site id or any legacy unit id may identify the site.
- [Facility relationships](https://docs.gdeltcloud.com/api-reference/facilities/facility-relationships.md): Evidence-backed physical hierarchy in data and participant assertions in participants. Each collection has independent pagination; follow pagination.next_cursor for links and meta.participant_pagination.next_cursor for participants using offset. Reported and probable claims are usable by default. In…
- [Facility source observations](https://docs.gdeltcloud.com/api-reference/facilities/facility-source-observations.md): Dated physical facility observations from every contributing source, including native capacity, material basis, units and shared-capacity groups. These observations are evidence, not additive capacity totals. Withheld fields remain unknown; deep compute and financing are separately gated.
- [Inspect a bounded Facilities example](https://docs.gdeltcloud.com/api-reference/facilities/inspect-a-bounded-facilities-example.md): Public, dated captures of real facility detail, participant relationships and observations. Choose mountain-pass, rotterdam or colossus. These bounded examples retain source evidence and limitations; they are not live searches or complete historical snapshots. Arbitrary Facilities requests retain cu…
- [List Monitors](https://docs.gdeltcloud.com/api-reference/monitors/list-monitors.md): List the active organization’s shared Monitors and the caller’s current Monitor capabilities. Scheduled checks consume 0 QU.
- [Create Monitor](https://docs.gdeltcloud.com/api-reference/monitors/create-monitor.md): Create one organization-shared Monitor. When a webhook destination is first configured, webhook_signing_secret is returned once.
- [Get Monitor](https://docs.gdeltcloud.com/api-reference/monitors/get-monitor.md): Get one organization-shared Monitor, including its canonical subject, criteria, schedule, delivery state, and legacy compatibility marker.
- [Delete Monitor](https://docs.gdeltcloud.com/api-reference/monitors/delete-monitor.md): Permanently delete one Monitor and its retained runs.
- [Update Monitor](https://docs.gdeltcloud.com/api-reference/monitors/update-monitor.md): Update one Monitor. A new webhook_signing_secret is returned once only when the destination is first configured or explicitly rotated.
- [Preview Monitor](https://docs.gdeltcloud.com/api-reference/monitors/preview-monitor.md): Executes one on-demand Preview of the same standing question that `POST /api/v2/monitors` accepts, without saving, enabling or delivering it. Browser and API-key calls have the same non-delivering behavior. Body field history_days=7 (default) or 30 returns setup_preview: matching records by type, ac…
- [Batch enable, pause, or delete](https://docs.gdeltcloud.com/api-reference/monitors/batch-enable-pause-or-delete.md): Enable, pause, or delete up to 100 submitted Monitor ids. The response distinguishes submitted, unique, actually changed, and not-found ids; already-in-target-state rows are successful idempotent no-ops.
- [List triggered Monitor runs](https://docs.gdeltcloud.com/api-reference/monitors/list-triggered-monitor-runs.md): List the Monitor’s triggered runs retained for seven days. result_count, retained_row_count, and results.length describe different quantities.
- [Get a triggered Monitor run](https://docs.gdeltcloud.com/api-reference/monitors/get-a-triggered-monitor-run.md): Get one triggered run with bounded canonical matches and exact replay instructions. Follow every cursor and then apply exact_window_filter.
- [Send a test webhook](https://docs.gdeltcloud.com/api-reference/monitors/send-a-test-webhook.md): Tests every delivery channel this Monitor actually uses and reports each one under `channels`. A configured webhook receives the first attempt of a signed `monitor.test` event, synchronously; a retryable failure persists `retry_at` for the retry worker. Configured email receives a real test message…
- [Page a run's matched items](https://docs.gdeltcloud.com/api-reference/monitors/page-a-runs-matched-items.md): Pages the COMPLETE list of items one triggered run matched, as it was at trigger time, with the current state of each hydrated live. `GET /api/v2/monitors/{id}/runs/{runId}` embeds a bounded SAMPLE of cards; this operation walks the whole matched set. Each entry carries `as_triggered` — exactly what…
- [Export a run's matched items as CSV](https://docs.gdeltcloud.com/api-reference/monitors/export-a-runs-matched-items-as-csv.md): Downloads every retained matched item for a Monitor run as UTF-8 CSV. The export includes the frozen as-triggered fields, the current hydrated card, reconciliation status, and run-level counts. It takes no query parameters and may contain fewer rows than result_count when the writer reports matched_…
- [Run a saved Monitor now](https://docs.gdeltcloud.com/api-reference/monitors/run-a-saved-monitor-now.md): Executes the saved Monitor immediately and persists a seven-day run, including zero-match results. It costs 1 query unit, sends no email or webhook, does not advance match state, and does not change the schedule. Empty windows may return `historical_example` and `historical_example_status`, also ret…
- [Try a signed demo webhook](https://docs.gdeltcloud.com/api-reference/monitors/try-a-signed-demo-webhook.md): Explicitly sends one sample monitor.test event to GDELT Cloud’s temporary first-party receiver and returns the signed request and verified response. Takes only an optional name; no customer URL, email or Monitor ID is accepted. Creates no saved Monitor and sends no email. The receiver capability exp…
- [List saved queries](https://docs.gdeltcloud.com/api-reference/saved-queries/list-saved-queries.md): Lists private queries belonging to the caller and shared queries in their current workspace. No data query executes and no query units are charged. At most 500 recipes are returned.
- [Save a query](https://docs.gdeltcloud.com/api-reference/saved-queries/save-a-query.md): Saves validated filters and a fixed or rolling UTC time specification. Private by default; workspace sharing uses the authenticated current workspace. Authentication fields, results and pagination are not supported. Do not put secrets in query text.
- [Get a saved query](https://docs.gdeltcloud.com/api-reference/saved-queries/get-a-saved-query.md): Returns the recipe and a validated Explore URL. Rolling dates resolve at request time. An incompatible filter returns incompatibility with href=null; it is never silently discarded.
- [Delete a saved query](https://docs.gdeltcloud.com/api-reference/saved-queries/delete-a-saved-query.md): Deletes a recipe owned by the caller. Does not delete or pause any Monitor.
- [Update a saved query](https://docs.gdeltcloud.com/api-reference/saved-queries/update-a-saved-query.md): The creator can rename, edit, pin, change explicit workspace sharing or record reopening. Execution filters are revalidated when edited; reopening validates compatibility. Sharing does not grant edit permission to other members.
- [List Admin1 Values](https://docs.gdeltcloud.com/api-reference/geography/list-admin1-values.md): Discover the admin1 (state / province / oblast) values available for one country, measured over a trailing window of the settled Events table and canonicalised to exactly the tokens the `admin1` filter on `/api/v2/events` and `/api/v2/stories` accepts — so discover→filter round-trips without guessin…
- [Read country activity](https://docs.gdeltcloud.com/api-reference/geography/read-country-activity.md): Country publication aggregates and hourly evidence from the shared activity journal. Additions, updates and linked entities are separate metrics. Facility additions count published registry records (units), not newly built or deduplicated physical sites; country context inventories expose site and u…
- [Get country context](https://docs.gdeltcloud.com/api-reference/geography/get-country-context.md): Country activity, dated economic/resource fundamentals, facilities and political-office inventories with evidence links. Unknown values remain null. Country association does not imply citizenship or headquarters. Counts of people, office-holder records, facilities and units are qualified separately.
- [Federal Awards (USAspending)](https://docs.gdeltcloud.com/api-reference/government/federal-awards-usaspending.md): US federal award exposure for an entity — USAspending prime awards (contracts + grants) resolved to the entity spine. Look a subject up three ways (at least one is required): a resolved spine `entity_id` (`entity=`), a SAM.gov Unique Entity Identifier (`uei=`), or a fuzzy recipient name (`recipient=…
- [Foreign Agents (FARA)](https://docs.gdeltcloud.com/api-reference/government/foreign-agents-fara.md): US foreign-influence graph — DOJ FARA registrations linking a US registrant (law/lobby/PR firm) to the foreign principal it represents, resolved to the entity spine. Filter by a resolved `entity` (matches EITHER side of the link), a fuzzy `registrant` or `foreign_principal` name, or a `country`; `ad…
- [List Offices](https://docs.gdeltcloud.com/api-reference/political-offices/list-offices.md): Public political offices — legislative seats, cabinet posts, heads of state and government, courts, security and financial offices and IGO posts — one row per office, dataset-independent, with holder counts. Scope and branch are derived from the source's `gov.*` topics so they are closed, filterable…
- [Get Office](https://docs.gdeltcloud.com/api-reference/political-offices/get-office.md): One office by id — the Wikidata QID (`Q…`) or the `p_…` id `/api/v2/offices` serves — with a capped preview of its holders ordered current → ended → unknown. `holders_truncated` says when to walk `holders_url` instead. A name is not looked up here: resolve it on the list first.
- [List Office Holders](https://docs.gdeltcloud.com/api-reference/political-offices/list-office-holders.md): The valid-time roster of one office: every (holder, term) the publishers assert, ordered current → ended → unknown and most recent start first. Two datasets asserting one term are ONE row naming both sources. Holders are terminal spine ids collapsed through the arbiter; a holder the binder did not m…
- [List Entity Offices](https://docs.gdeltcloud.com/api-reference/political-offices/list-entity-offices.md): Every public office one entity has held, as the publishers assert it. `{entity_id}` accepts a spine `e_…` id, a news `wiki:` / `llm:` id, or a wikipedia_url, resolved through the same arbiter every other surface uses — a merged-away alias still finds its rows. An entity that resolves but holds no of…
- [List SEC filings](https://docs.gdeltcloud.com/api-reference/filings/list-sec-filings.md): List the SEC EDGAR filing index by company (CIK), form type, name, and date window. Requires a plan with SEC filings access (`can_use_filings`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Summarize filings](https://docs.gdeltcloud.com/api-reference/filings/summarize-filings.md): Rollup of filings by form type, date, or filer — counts + distinct filers. Requires a plan with SEC filings access (`can_use_filings`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Material events (8-K)](https://docs.gdeltcloud.com/api-reference/filings/material-events-8-k.md): Dated 8-K material corporate events (M&A, material agreements, executive changes, bankruptcies, delistings, impairments) extracted from 8-K bodies, with counterparties resolved into the entity spine. Requires a plan with SEC filings access (`can_use_filings`) — see [Pricing](https://gdeltcloud.com/p…
- [Filer profile](https://docs.gdeltcloud.com/api-reference/filings/filer-profile.md): A filer's identity, ticker, resolved entity_id, recent filings, and XBRL financial highlights. Requires a plan with SEC filings access (`can_use_filings`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Filer relations (LLM)](https://docs.gdeltcloud.com/api-reference/filings/filer-relations-llm.md): Subsidiary / supplier / customer / jurisdiction edges for a filer, derived from filing text through GDELT Cloud's proprietary AI pipeline and resolved to entity_ids with evidence. Requires a plan with SEC filings access (`can_use_filings`) — see [Pricing](https://gdeltcloud.com/pricing) for the plan…
- [Filer XBRL facts](https://docs.gdeltcloud.com/api-reference/filings/filer-xbrl-facts.md): XBRL structured financial facts for a filer — a concept time series for exposure sizing. Requires a plan with SEC filings access (`can_use_filings`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Resolve to CIK](https://docs.gdeltcloud.com/api-reference/filings/resolve-to-cik.md): Resolve a company name, ticker, or CIK to SEC filing identities and terminal spine entities.
- [GLEIF legal entities (Open Feed)](https://docs.gdeltcloud.com/api-reference/reference-data/gleif-legal-entities-open-feed.md): The GLEIF Global LEI Index — 3.39M legal entities with their registered name, jurisdiction, entity and registration status, legal form and registration authority, served close to as-published. **At least one filter is required**: the feed covers 3.39M records, so an unfiltered listing is refused wit…
- [One GLEIF entity, with its relationships and ISINs](https://docs.gdeltcloud.com/api-reference/reference-data/one-gleif-entity-with-its-relationships-and-isins.md): The full Level-1 record for a single LEI plus its Level-2 relationships, any declared reporting exceptions, and its LEI↔ISIN mappings. A structurally impossible LEI returns 400 INVALID_LEI (it fails the ISO 17442 check digit); a well-formed LEI we do not hold returns 404. Corporate hierarchy as repo…
- [GLEIF Level-2 relationships](https://docs.gdeltcloud.com/api-reference/reference-data/gleif-level-2-relationships.md): Parent/child relationship records as filed with the Global LEI System. `lei` matches EITHER endpoint. Note the direction convention in the source data: the start node is the CHILD and the end node is the PARENT. Corporate hierarchy as reported to the Global LEI System: accounting consolidation under…
- [LEI ↔ ISIN mappings](https://docs.gdeltcloud.com/api-reference/reference-data/lei-↔-isin-mappings.md): Resolve an LEI to its issued ISINs, or an ISIN back to its LEI. One of `lei` or `isin` is required — the mapping table holds ~9M rows and an unfiltered listing is refused with 400 FILTER_REQUIRED. Plan-gated: requires the `can_use_gleif` entitlement (Analyst plan and up); non-entitled plans receive…
- [Search Energy Assets](https://docs.gdeltcloud.com/api-reference/energy/search-energy-assets.md): Search Global Energy Monitor energy-infrastructure assets across all 15 trackers. Returns clean asset cards with native capacity, MW capacity where meaningful, normalized geography, ownership arrays, GEM Wiki URLs, and detail/API links.
- [Summarize Energy Assets](https://docs.gdeltcloud.com/api-reference/energy/summarize-energy-assets.md): Aggregate counts and MW rollups across Energy assets. Summary endpoints use structured filters only. capacity_mw fields are meaningful for power-generation trackers; constrain tracker when comparing capacity across unit families.
- [Map Energy Assets](https://docs.gdeltcloud.com/api-reference/energy/map-energy-assets.md): Return map-ready Energy asset data. Without a single explicit country filter, the endpoint returns aggregate country-centroid rows. With exactly one country filter and no region or continent, it returns fine-grained asset pins capped by map_limit/fine_grained_limit.
- [Get Energy Asset](https://docs.gdeltcloud.com/api-reference/energy/get-energy-asset.md): Fetch one Energy asset by tracker and GEM ID. The response includes the canonical asset card plus a raw source record containing tracker-specific fields.
- [Search Energy Owners](https://docs.gdeltcloud.com/api-reference/energy/search-energy-owners.md): Search the Global Energy Monitor ownership registry for canonical owner entities. Use this endpoint to resolve a company, government owner, person, or investment vehicle to a GEM Entity ID before calling owner portfolio or exposure endpoints.
- [Get Energy Owner](https://docs.gdeltcloud.com/api-reference/energy/get-energy-owner.md): Fetch one Global Energy Monitor ownership entity by GEM Entity ID, including parent IDs, external IDs, and a portfolio summary across Energy assets. Optional include_exposure=true adds plan-gated risk/exposure fields — requires `can_use_exposure` (see [Pricing](https://gdeltcloud.com/pricing) for th…
- [GEM gas project finance](https://docs.gdeltcloud.com/api-reference/energy/gem-gas-project-finance.md): LNG and gas-power financing and procurement observations. Repeated project totals are evidence, never summed across financiers. Header units and native values remain explicit; unresolved parties stay visible.
- [AI models](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-models.md): Epoch model observations with terminal entity IDs, separately resolved participants, source roles and publication coverage.
- [AI hardware](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-hardware.md): Epoch accelerator observations, manufacturer/foundry participants and release coverage.
- [AI data centers](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-data-centers.md): Epoch compute and finance observations linked to physical Facilities. Curated inventory totals are not a worldwide census; participant roles and ownership certainty remain explicit.
- [AI companies](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-companies.md): Tracked labs with dated financial observations and terminal entity links. Latest valuation uses closed rounds.
- [AI chip sales](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-chip-sales.md): Latest cumulative observations per chip designer; totals are not summed across alternate windows.
- [GPU clusters](https://docs.gdeltcloud.com/api-reference/ai-compute/gpu-clusters.md): Epoch cluster observations with status, certainty, hardware and source evidence; clusters remain distinct from physical buildings.
- [AI chip owners](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-chip-owners.md): Quarterly and cumulative chip ownership estimates with original median and uncertainty fields, resolved participants and native units.
- [AI chip users](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-chip-users.md): Lab compute-use estimates and intermediate calculations, preserving units, periods and uncertainty.
- [AI chip components](https://docs.gdeltcloud.com/api-reference/ai-compute/ai-chip-components.md): Logic, packaging and memory component estimates; chip and designer totals and supply denominators remain distinct collections.
- [Epoch observations](https://docs.gdeltcloud.com/api-reference/ai-compute/epoch-observations.md): Typed Epoch source collections, including dated finance, cooling, quantity and timeline observations. Native fields retain units, qualifiers and uncertainty.
- [List FRED series](https://docs.gdeltcloud.com/api-reference/macro-finance/list-fred-series.md): List the FRED economic time-series catalog by title/ID search, agency, frequency, and seasonal adjustment. Call with no filters to enumerate the full curated catalog (ordered by popularity) — this is the way to discover a valid `series_id`. Quarantined (third-party copyrighted) series are never retu…
- [Get FRED series detail](https://docs.gdeltcloud.com/api-reference/macro-finance/get-fred-series-detail.md): Series catalog detail plus the most recent 24 observations (latest vintage). An unknown or quarantined series_id returns 404 with a message pointing to GET /api/v2/macro/series and the catalog. Requires a plan with Macro & economic data access (`can_use_macro`) — see [Pricing](https://gdeltcloud.com…
- [List FRED observations](https://docs.gdeltcloud.com/api-reference/macro-finance/list-fred-observations.md): Point-in-time observations for a single series. Optional `as_of` selects the vintage known on/before that date (ALFRED — no look-ahead); otherwise the latest vintage is returned. When no dates are given, returns the most-recent observations across the full available history, bounded by `limit` — pag…
- [List FRED releases](https://docs.gdeltcloud.com/api-reference/macro-finance/list-fred-releases.md): Rollup of the catalog by source agency and release, with series counts. Requires a plan with Macro & economic data access (`can_use_macro`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [Screen a counterparty](https://docs.gdeltcloud.com/api-reference/screening-and-reference/screen-a-counterparty.md): Recall-first restricted-party candidate retrieval with explicit match evidence. Retrieval similarity is not an identity probability and is exposed separately from match confidence.
- [Ownership-chain exposure](https://docs.gdeltcloud.com/api-reference/screening-and-reference/ownership-chain-exposure.md): Precomputed entity and facility exposure through sanctions, China, or state-ownership chains. Numeric stake filters apply to effective chain stake, never the direct asset-owner percentage alone. A configured registry requires positive source publication; unavailable publication returns 503 SOURCE_UN…
- [List catalog](https://docs.gdeltcloud.com/api-reference/screening-and-reference/list-catalog.md): Catalog of the restricted-party list sources we ingest — issuer, jurisdiction, category, publisher provenance, refresh cadence, whether the source publishes natural persons, and the current entry count. The index for `/api/v2/lists/entries` and `/api/v2/screening/match`: every `source_key` here with…
- [Search list entries](https://docs.gdeltcloud.com/api-reference/screening-and-reference/search-list-entries.md): Search the entries on the restricted-party lists — by name or alias, country, programme, or resolved entity — current or point-in-time. Each entry carries its aliases, `entity_kind` (`entity` | `vessel` | `aircraft` | `individual`), programmes, legal basis, cross-source ids and our first/last observ…
- [List change feed](https://docs.gdeltcloud.com/api-reference/screening-and-reference/list-change-feed.md): The daily diff feed for the restricted-party lists — who was added, removed or changed on each snapshot date. Snapshot dates are OUR observation dates; the feed begins at `coverage_window.start` on `/api/v2/screening/match`. Without a window it returns the most recent changes first.
- [China dev-finance projects](https://docs.gdeltcloud.com/api-reference/china/china-dev-finance-projects.md): China overseas development-finance projects (AidData GCDF) — amounts, sector, status, financiers; joinable to the live event stream by country. Requires a plan with China development finance access (`can_use_china`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it.
- [China dev-finance rollup](https://docs.gdeltcloud.com/api-reference/china/china-dev-finance-rollup.md): Rollup of China overseas development finance by country, sector, status, commitment year, flow class, or funding intent — counts + total committed USD. Requires a plan with China development finance access (`can_use_china`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include i…
- [Chokepoint transit activity](https://docs.gdeltcloud.com/api-reference/maritime/chokepoint-transit-activity.md): Hourly vessel-flow rollup for maritime chokepoints, derived from terrestrial AIS. Each row is one chokepoint·hour with vessel counts and average speed. Requires a plan with Maritime intelligence access (`can_use_maritime`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that include it…
- [Current vessels (last-known)](https://docs.gdeltcloud.com/api-reference/maritime/current-vessels-last-known.md): Current vessels with their last-known position and identity, derived from terrestrial AIS. Positions are LAST-KNOWN ONLY — there is no raw position-track endpoint. This is current state, so it takes no date window. Requires a plan with Maritime intelligence access (`can_use_maritime`) — see [Pricing…
- [Vessel by IMO](https://docs.gdeltcloud.com/api-reference/maritime/vessel-by-imo.md): One vessel by IMO number: identity, last-known position, and the matched Global Energy Monitor LNG carrier (when one exists). Position is LAST-KNOWN ONLY — no raw track. Returns 404 when no vessel identity exists for the IMO. Requires a plan with Maritime intelligence access (`can_use_maritime`) — s…
- [Chokepoint dwell episodes](https://docs.gdeltcloud.com/api-reference/maritime/chokepoint-dwell-episodes.md): Dwell episodes — completed arrival→departure stays at maritime chokepoints, derived from terrestrial AIS. Each row is one vessel's stay with its dwell duration. Requires a plan with Maritime intelligence access (`can_use_maritime`) — see [Pricing](https://gdeltcloud.com/pricing) for the plans that i…
- [AIS-dark gaps](https://docs.gdeltcloud.com/api-reference/maritime/ais-dark-gaps.md): AIS-dark gaps — intervals where a vessel stopped broadcasting AIS then reappeared, derived from terrestrial AIS coverage. Each row is one gap with the last-known position before it went dark. Requires a plan with Maritime intelligence access (`can_use_maritime`) — see [Pricing](https://gdeltcloud.co…
- [Area activity over time](https://docs.gdeltcloud.com/api-reference/maritime/area-activity-over-time.md): Aggregate vessel activity over an area, bucketed by hour or day — distinct vessels, total + moving positions, and average/max speed per bucket. Generalizes /transits to arbitrary geography (chokepoint, bounding box, or proximity). The "is this area's traffic anomalous vs the baseline" view. Requires…
- [Spatial density grid](https://docs.gdeltcloud.com/api-reference/maritime/spatial-density-grid.md): Spatial density grid (heatmap) of position and vessel counts per lat/lon cell within an area. Shows where traffic concentrates. AREA REQUIRED — pass bbox, near, or near_gem_id. Requires a plan with Maritime intelligence access (`can_use_maritime`) — see [Pricing](https://gdeltcloud.com/pricing) for…
- [Raw position points in an area](https://docs.gdeltcloud.com/api-reference/maritime/raw-position-points-in-an-area.md): ⚠️ RAW position points (the actual AIS track) inside an area over time — each row a single fix (time, position, speed, course, nav status). AREA REQUIRED — pass chokepoint, bbox, near, or near_gem_id. Keyset-paginated: follow the opaque next_cursor to stitch a long window into pages rather than one…
- [One vessel's track over time](https://docs.gdeltcloud.com/api-reference/maritime/one-vessels-track-over-time.md): ⚠️ RAW position track for a single vessel by IMO — the literal 'this ship over time': every AIS fix (time, position, speed, course, heading, nav status) across the window, time-ordered. Keyset-paginated: follow the opaque next_cursor to stitch a long window into pages rather than one giant response.…
- [Ports reference](https://docs.gdeltcloud.com/api-reference/maritime/ports-reference.md): The open-data ports reference (NGA World Port Index) — ~3,800 ports with coordinates, UN/LOCODE, harbor size/type/use, max vessel draft, channel depth, and container / oil / LNG terminal facilities. Filter by country, harbor size, terminal type, name, or proximity to a point / GEM energy asset. This…
- [Port disruption pulse](https://docs.gdeltcloud.com/api-reference/maritime/port-disruption-pulse.md): Port-level disruption intelligence — geo-fuses the WPI ports reference with GDELT events near each port (within `event_radius_km` over the last `days`): relevant-event volume, conflict signal, a 7d-vs-baseline anomaly ratio, recent headlines, nearby flagged-energy-asset exposure, and AIS-coverage co…
- [Chokepoint risk watch](https://docs.gdeltcloud.com/api-reference/maritime/chokepoint-risk-watch.md): The maritime risk layer — fuses each chokepoint's AIS coverage confidence (live / sparse / dark) and 24h/7d transit activity with GDELT conflict events (last 7 days) in its bordering countries, plus nearby flagged-energy-asset exposure. Surfaces the 'blind spot': high conflict signal but no vessel c…
- [Atlas GPR — geopolitical risk vs a place’s own normal](https://docs.gdeltcloud.com/api-reference/atlas-intelligence/atlas-gpr-—-geopolitical-risk-vs-a-place’s-own-normal.md): Vintaged Atlas GPR readings for one explicit geographic level and place. Every accepted query parameter is declared here; undeclared geographic shortcuts such as `country=` fail with UNKNOWN_PARAM rather than returning the World series. Country own_coverage rows may include a separate best_effort ca…
- [Atlas Posture — country condition and annual context](https://docs.gdeltcloud.com/api-reference/atlas-intelligence/atlas-posture-—-country-condition-and-annual-context.md): A 0–100 condition score with explicit dynamic and structural axes. Sparse Event windows retain null dynamic scores. Available annual WDI/WGI/V-Dem indicators can supply a structural-only headline, marked best_effort with its evidence note, indicator count and vintage. Headline insufficient_data mean…
- [Atlas coverage — where the index can and cannot be read](https://docs.gdeltcloud.com/api-reference/atlas-intelligence/atlas-coverage-—-where-the-index-can-and-cannot-be-read.md): Per-country coded-event coverage over a trailing window, and therefore which country-level Atlas products (Pulse, Posture) each country is dense enough to serve today. Read it BEFORE treating a `null` Atlas reading as calm: below the floors means unknown, not quiet. All 206 countries are enumerated,…
- [Natural-resource statistics](https://docs.gdeltcloud.com/api-reference/natural-resources/natural-resource-statistics.md): USGS country and aggregate production, reserves and qualified statistics. Values preserve unknown, suppressed, qualitative and bounded observations. Country totals are independent of the Facilities inventory. Country/region/continent filters select country-scope rows only; use include_summary for fu…
- [Value vocabularies, machine-readable](https://docs.gdeltcloud.com/api-reference/meta/value-vocabularies-machine-readable.md): Every vocabulary the API validates against, with the value-space of each — `closed` (the complete authoritative set, safe to switch on), `observed` (a dated measurement of what the corpus currently holds, never an allowlist) and `identifier` (a key with a format and a resolver, never enumerated). Ca…
- [Endpoint contracts, machine-readable](https://docs.gdeltcloud.com/api-reference/meta/endpoint-contracts-machine-readable.md): The contract-governed endpoints and every parameter each one accepts — names, aliases, bounds, defaults, the vocabulary a value is validated against, and the params deliberately rejected with what to use instead. Served from the same descriptors the API imports at request time, so it cannot describe…
- [What a call costs, and what your plan allows](https://docs.gdeltcloud.com/api-reference/meta/what-a-call-costs-and-what-your-plan-allows.md): The query-unit cost model and this key's current allowance and measured consumption. Pricing remains available when usage aggregation is delayed: usage.measurement_status is fresh, stale, or pending; unknown consumption, remaining allowance, and percentages are null rather than zero or unlimited. Us…
- [Reference](https://docs.gdeltcloud.com/reference/index.md): The generated tier — every value, parameter, code and formula, emitted from the objects the server imports at request time.
- [Endpoint index](https://docs.gdeltcloud.com/reference/endpoints.md): Every operation the v2 API publishes, on one page, grouped by domain.
- [Parameter reference](https://docs.gdeltcloud.com/reference/parameters.md): Shared and identifier parameters across the v2 API, plus the full parameter list for the contract-governed endpoints.
- [Error reference](https://docs.gdeltcloud.com/reference/errors.md): Every `code` the v2 API returns, what it means, and what to do about it.
- [API stability and deprecation](https://docs.gdeltcloud.com/reference/stability.md): What we commit to before a breaking change, what deprecated/retired/removed each mean, and how to be told.
- [Value reference](https://docs.gdeltcloud.com/reference/enums.md): Every value the API validates against — closed vocabularies, observed vocabularies, and identifier spaces.
- [Event metric reference](https://docs.gdeltcloud.com/reference/metrics.md): What each event metric measures, what you can do with it, and how it is computed.
- [Magnitude](https://docs.gdeltcloud.com/reference/metrics/magnitude.md): What `magnitude` measures, what you can do with it, how it is computed, and what it does not claim.
- [Systemic importance](https://docs.gdeltcloud.com/reference/metrics/systemic-importance.md): What `systemic_importance` measures, what you can do with it, how it is computed, and what it does not claim.
- [Propagation potential](https://docs.gdeltcloud.com/reference/metrics/propagation-potential.md): What `propagation_potential` measures, what you can do with it, how it is computed, and what it does not claim.
- [Market sensitivity](https://docs.gdeltcloud.com/reference/metrics/market-sensitivity.md): What `market_sensitivity` measures, what you can do with it, how it is computed, and what it does not claim.
- [Core articles](https://docs.gdeltcloud.com/reference/core-articles.md): What makes an article core to a story, how articles are ranked, and what the derived counts mean.
- [Complete Event Taxonomy](https://docs.gdeltcloud.com/reference/taxonomy-complete.md): The authoritative, generated reference for every ACLED and CAMEO+ code GDELT Cloud emits.
- [Conflict event codes](https://docs.gdeltcloud.com/reference/codes-conflict.md): What each ACLED sub-event type means — definition, inclusions, exclusions and Goldstein anchor.
- [CAMEO POLITICAL codes — cooperation](https://docs.gdeltcloud.com/reference/codes-political-cooperation.md): Roots 01-09: statements, appeals, intent, consultation, aid and concessions — defined.
- [CAMEO POLITICAL codes — conflict](https://docs.gdeltcloud.com/reference/codes-political-conflict.md): Roots 10-17: demands, disapproval, rejection, threats, force posture and coercion — defined.
- [CAMEO+ domain codes](https://docs.gdeltcloud.com/reference/codes-domains.md): What each non-political CAMEO+ code means — the nine domains GDELT Cloud adds to CAMEO.
- [Crime and justice](https://docs.gdeltcloud.com/reference/codes-crime.md): What each `CRIME` code means — definition, inclusions and exclusions for all 10 codes.
- [Economic structure](https://docs.gdeltcloud.com/reference/codes-economic.md): What each `ECONOMIC` code means — definition, inclusions and exclusions for all 7 codes.
- [Industrial capacity](https://docs.gdeltcloud.com/reference/codes-corporate.md): What each `CORPORATE` code means — definition, inclusions and exclusions for all 8 codes.
- [Technology power](https://docs.gdeltcloud.com/reference/codes-technology.md): What each `TECHNOLOGY` code means — definition, inclusions and exclusions for all 6 codes.
- [Infrastructure](https://docs.gdeltcloud.com/reference/codes-infrastructure.md): What each `INFRASTRUCTURE` code means — definition, inclusions and exclusions for all 6 codes.
- [Environmental shocks](https://docs.gdeltcloud.com/reference/codes-environment.md): What each `ENVIRONMENT` code means — definition, inclusions and exclusions for all 5 codes.
- [Public health](https://docs.gdeltcloud.com/reference/codes-health.md): What each `HEALTH` code means — definition, inclusions and exclusions for all 5 codes.
- [Demographic structure](https://docs.gdeltcloud.com/reference/codes-demographic.md): What each `DEMOGRAPHIC` code means — definition, inclusions and exclusions for all 5 codes.
- [Information space](https://docs.gdeltcloud.com/reference/codes-information.md): What each `INFORMATION` code means — definition, inclusions and exclusions for all 4 codes.
- [MCP server](https://docs.gdeltcloud.com/mcp/overview.md): Connect Claude, ChatGPT or your own agent to GDELT Cloud in about two minutes.
- [Tools](https://docs.gdeltcloud.com/mcp/tools.md): 116 named data operations, optional discovery and account/Monitor helpers.
- [Integrations](https://docs.gdeltcloud.com/mcp/integrations.md): One URL, every MCP client.
- [Plugins](https://docs.gdeltcloud.com/mcp/plugins.md): One command wires both MCP servers and eight skills into Claude Code, Codex or Cursor.
- [Skills](https://docs.gdeltcloud.com/mcp/skills.md): Packaged workflows the MCP server loads on demand.
- [Supporting research](https://docs.gdeltcloud.com/mcp/external-tools.md): Bounded supporting web research and native economic data
- [AGENTS](https://docs.gdeltcloud.com/AGENTS.md)

## OpenAPI Specs

- [openapi-v2](/api-reference/openapi-v2.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.