GDELT Cloud Docs — Global Event Data API & MCP

Overview

The gdelt_cloud_* MCP wrappers expose the public API v2 product catalog:

structured Events: conflict and cameoplus
clustered Stories with article evidence
Event and Story summaries
Entities linked to Events and Stories
country-scoped admin1 discovery
Facilities — the unified physical-asset directory (facilities_search, facilities_get, facilities_by_owner; plan-gated, Analyst+)
Monitoring Briefs — create_brief, list_briefs, get_brief (plan-gated; see Monitoring Briefs)

Use plain English country names in examples and user-facing calls. ISO-3 and legacy FIPS aliases are accepted, but normalized outputs use country names. region and continent expand to ISO-3 country lists on the API backend. Event tools match those countries against Event location plus actor-origin countries. Story tools use the same country-list expansion through linked Event primary location only. Event, Story, and Entity list tools default to the exact past 24 hours. Narrow with geography, category, subcategory, civilian-targeting filters, date windows up to 30 days, and semantic search rather than public confidence modes. subcategory requires its parent category. Detail tools (get_event, get_story, and Story articles) resolve known IDs directly. List and detail tools preserve API-enriched visual context by default: top source-article sharing images, source-domain avatars, and linked Entity thumbnails when available. These fields are for product rendering and analyst orientation; absence of an image is not evidence about the underlying Event, Story, or Entity.

Wrapper Parameters

Wrapper	Parameter	Required	Description
`gdelt_cloud_tool_list`	none	no	Lists available GDELT Cloud nested tools.
`gdelt_cloud_tool_get`	`tool_name`	conditional	Single nested tool name to inspect.
`gdelt_cloud_tool_get`	`tool_names`	conditional	List of nested tool names to inspect together.
`gdelt_cloud_tool_get`	`category`	no	Optional Event parent category such as `TECHNOLOGY`, `INFRASTRUCTURE`, `Protests`, or `Battles`; when present, Event/Story/Entity taxonomy tools return only that category’s scoped `subcategory` enum.
`gdelt_cloud_tool_call`	`tool_name`	yes	Exact nested tool name to execute.
`gdelt_cloud_tool_call`	`tool_arguments`	no	Object containing the selected nested tool’s parameters.

Shared Date Parameters

Range-capable tools accept start_date, end_date, and days.

Parameter	Required	Description
`start_date`	no	Inclusive start date in `YYYY-MM-DD`. With `end_date`, defines an explicit window of at most 30 days.
`end_date`	no	Inclusive end date in `YYYY-MM-DD`. Defaults to current UTC date when omitted with `days`.
`days`	no	Window size from 1 to 30. Used to complete the range when either date is omitted.

Precedence:

start_date + end_date: use the explicit inclusive range.
start_date + days: compute end_date.
end_date + days: compute start_date.
days only: trailing window ending current UTC date. On list tools, the default days=1 returns the exact past 24 hours.

`search_events`

Use for incident-level structured records: protests, attacks, diplomatic actions, infrastructure projects, economic policy events, and other coded Events.

Parameter	Required	Description
`start_date`	no	Inclusive start date, max 30-day window.
`end_date`	no	Inclusive end date, max 30-day window.
`days`	no	Window size, 1-30. Default 7.
`country`	no	Plain English country name; broad location-or-actor-origin matching.
`region`	no	Plain English region such as `Middle East` or `Western Africa`; expands to an ISO-3 country list and matches Event location plus actor-origin countries.
`continent`	no	Plain English continent such as `Asia` or `Europe`; expands to an ISO-3 country list and matches Event location plus actor-origin countries.
`admin1`	no	State/province/admin1 location filter. Discover with `list_admin1`.
`event_family`	no	Deprecated legacy filter: `conflict` or `cameoplus`. Prefer `category`, which implies the family.
`category`	no	Single product category enum: a Conflict event type such as `Battles`, `Protests`, or `Explosions/Remote violence`, or a CAMEO+ domain such as `POLITICAL`, `CRIME`, or `INFRASTRUCTURE`.
`categories`	no	Multi-select product categories. Values are OR’d together and serialized to the API as `category=Battles,CRIME`.
`subcategory`	no	Specific Event subtype. Requires `category` or `categories`; for Conflict categories, use sub-event types such as `Armed clash`, `Peaceful protest`, or `Air/drone strike`. For CAMEO+ categories, use stable event codes such as `TE01` or `IN03`; older label text is accepted as a compatibility alias.
`domain`	no	Deprecated legacy CAMEO+ domain filter. Prefer `category` for new integrations.
`search`	no	Semantic search text; not a keyword-only filter.
`has_fatalities`	no	Boolean fatality filter.
`civilian_targeting`	no	Boolean Conflict filter. `true` keeps Events where civilians are coded as the primary target.
Metric `_min` / `_max` filters	no	Canonical metric ranges: `significance`, `confidence`, `goldstein_scale`, `goldstein_severity`, `magnitude`, `systemic_importance`, `propagation_potential`, `market_sensitivity`.
`sort`	no	`significance` default, or `recent`.
`limit`	no	Number of Event cards, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.
`include_images`	no	Keep API-enriched article sharing images, source-domain avatars, and linked Entity thumbnails when available. Default `true`.

{
  "tool_name": "search_events",
  "tool_arguments": {
    "category": "INFRASTRUCTURE",
    "propagation_potential_min": 0.6,
    "continent": "Asia",
    "search": "new data center projects",
    "start_date": "2026-04-11",
    "end_date": "2026-04-17",
    "sort": "significance"
  }
}

`summarize_events`

Use for dashboards and trend charts before drilling into records. Summary tools do not accept search; use search_events first for semantic retrieval, then summarize with structured filters. For time-series plots, call with group_by=date across a meaningful recent window such as days=14 or days=30. Each returned bucket is one chronological observation with count fields plus metric aggregates such as Goldstein, magnitude, systemic importance, propagation potential, market sensitivity, significance, confidence, articles, and fatalities. Use gdelt_cloud_tool_get(tool_name="search_events", category="TECHNOLOGY") to retrieve the scoped subcategory enum before calling. Use group_by=subcategory when you want observed live buckets and counts after choosing a parent category. For example, summarize_events(category="Battles", group_by="subcategory") returns ACLED sub-event buckets such as Government regains territory; then call search_events(category="Battles", subcategory="Government regains territory") for the underlying Event cards. Metric filters apply before aggregation. significance and confidence apply across Event families; CAMEO+ detail filters only match scored CAMEO+ Events; Goldstein filters match Conflict and CAMEO+ POLITICAL Events. goldstein_severity is absolute intensity, not signed valence.

Parameter	Required	Description
`group_by`	no	`date`, `country`, `region`, `continent`, `category`, or `subcategory`. Default `date`.
`start_date`	no	Inclusive start date, max 30-day window.
`end_date`	no	Inclusive end date, max 30-day window.
`days`	no	Window size, 1-30. Default 30.
`country`	no	Plain English country name.
`region`	no	Plain English region; expands to an ISO-3 country list and summarizes matching Event locations plus actor-origin countries.
`continent`	no	Plain English continent; expands to an ISO-3 country list and summarizes matching Event locations plus actor-origin countries.
`admin1`	no	State/province/admin1 location filter.
`event_family`	no	Deprecated legacy filter: `conflict` or `cameoplus`. Prefer `category`, which implies the family.
`category`	no	Single product category enum: a Conflict event type or a CAMEO+ domain.
`categories`	no	Multi-select product categories. Values are OR’d together and serialized to the API as comma-separated `category`.
`subcategory`	no	Event subtype. Requires `category` or `categories`; use ACLED sub-event labels for Conflict categories and stable CAMEO+ event codes such as `TE01` for CAMEO+ categories. Validation errors include recoverable values.
`domain`	no	Deprecated legacy CAMEO+ domain filter. Prefer `category` for new integrations.
`has_fatalities`	no	Boolean fatality filter.
`civilian_targeting`	no	Boolean Conflict filter for civilian-targeting Events.
Metric `_min` / `_max` filters	no	Same canonical metric ranges as `search_events`, applied before summary aggregation.
`limit`	no	Maximum buckets, 1-500. Default 50.

`get_event`

Parameter	Required	Description
`event_id`	yes	Known Event ID returned by `search_events` or linked from a Story.
`include_images`	no	Keep API-enriched article sharing images and linked Entity thumbnails when available. Default `true`.

`search_stories`

Use for narrative clusters, article evidence, and story-first questions.

Parameter	Required	Description
`start_date`	no	Inclusive start date, max 30-day window.
`end_date`	no	Inclusive end date, max 30-day window.
`days`	no	Window size, 1-30. Default 7.
`country`	no	Plain English country name; matches Stories through linked Event primary location.
`region`	no	Plain English region; expands to an ISO-3 country list and matches Stories through linked Event primary location.
`continent`	no	Plain English continent; expands to an ISO-3 country list and matches Stories through linked Event primary location.
`admin1`	no	Location-only admin1 filter.
`category`	no	Linked Event category filter, such as `Battles`, `Protests`, `POLITICAL`, or `CRIME`.
`categories`	no	Multi-select linked Event categories. Values are OR’d together and serialized to the API as `category=Battles,CRIME`.
`subcategory`	no	Linked-Event subcategory. Requires `category` or `categories` and must belong to at least one selected linked-Event category. Use ACLED sub-event labels for Conflict categories and stable CAMEO+ event codes for CAMEO+ categories.
`story_category`	no	Legacy Story cluster category, such as `conflict_security`.
`event_category`	no	Deprecated alias for `category` on Story linked-Event filters.
`event_categories`	no	Deprecated alias for `categories` on Story linked-Event filters.
`domain`	no	Deprecated legacy linked CAMEO+ domain filter. Prefer `category`.
`search`	no	Semantic search text; not a keyword-only filter.
`has_events`	no	`true` narrows to Stories with at least one linked structured Event. `false` (default) returns all matching Stories.
`has_fatalities`	no	Boolean filter for Stories linked to fatal Events.
`civilian_targeting`	no	Boolean filter for Stories linked to Conflict Events where civilians are the primary target.
`article_count_min`	no	Minimum Story article count.
`article_count_max`	no	Maximum Story article count.
`sort`	no	`significance` default, or `recent`.
`limit`	no	Number of Story cards, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.
`include_images`	no	Keep API-enriched article sharing images, source-domain avatars, and linked Entity thumbnails when available. Default `true`.

`summarize_stories`

Use for dashboards and coverage trends before drilling into Story records. Summary tools do not accept search; use search_stories first for semantic retrieval, then summarize with structured filters. For trend plots and Brief benchmark panels, call with group_by=date across a recent history window. Story summaries expose story/article counts and linked-Event metric aggregates; they should not be confused with distinct Event totals. For group_by=category and group_by=subcategory, Story summary buckets use linked Event taxonomy. That makes them useful for coverage rollups such as category="Battles", group_by="subcategory" while preserving broad narrative coverage for date/geography summaries.

Parameter	Required	Description
`group_by`	no	`date`, `country`, `region`, `continent`, `category`, or `subcategory`. Default `date`.
`start_date`	no	Inclusive start date, max 30-day window.
`end_date`	no	Inclusive end date, max 30-day window.
`days`	no	Window size, 1-30. Default 30.
`country`	no	Plain English country name.
`region`	no	Plain English region; expands to an ISO-3 country list and summarizes Stories through linked Event primary location.
`continent`	no	Plain English continent; expands to an ISO-3 country list and summarizes Stories through linked Event primary location.
`admin1`	no	Location-only admin1 filter.
`category`	no	Linked Event category filter, such as `Battles`, `Protests`, `POLITICAL`, or `CRIME`.
`categories`	no	Multi-select linked Event categories. Values are OR’d together and serialized to the API as comma-separated `category`.
`subcategory`	no	Linked-Event subcategory. Requires `category` or `categories` and must belong to at least one selected linked-Event category. Use ACLED sub-event labels for Conflict categories and stable CAMEO+ event codes for CAMEO+ categories.
`story_category`	no	Legacy Story cluster category, such as `conflict_security`.
`event_category`	no	Deprecated alias for `category` on Story linked-Event filters.
`event_categories`	no	Deprecated alias for `categories` on Story linked-Event filters.
`domain`	no	Deprecated legacy linked CAMEO+ domain filter. Prefer `category`.
`has_events`	no	`true` narrows to Stories with at least one linked structured Event. `false` (default) returns all matching Stories.
`has_fatalities`	no	Boolean linked-fatality filter.
`civilian_targeting`	no	Boolean linked civilian-targeting filter.
`article_count_min`	no	Minimum Story article count.
`article_count_max`	no	Maximum Story article count.
`limit`	no	Maximum buckets, 1-500. Default 50.

`get_story`

Parameter	Required	Description
`story_id`	yes	Known Story ID returned by `search_stories` or linked from an Event.
`include_images`	no	Keep API-enriched article sharing images and linked Entity thumbnails when available. Default `true`.

`get_story_articles`

Parameter	Required	Description
`story_id`	yes	Known Story ID.
`limit`	no	Number of source articles, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.
`include_images`	no	Keep source-article sharing images and source-domain avatar URLs when available. Default `true`.

`search_entities`

Parameter	Required	Description
`search`	no	Entity name search string.
`type`	no	`person` or `organization`.
`start_date`	no	Inclusive start date, max 30-day window.
`end_date`	no	Inclusive end date, max 30-day window.
`days`	no	Window size, 1-30. Default 30.
`event_family`	no	Deprecated linked-evidence filter. Prefer `category`, which implies the family.
`category`	no	Linked Event category filter for Entity evidence.
`categories`	no	Multi-select linked Event categories serialized as comma-separated `category`.
`subcategory`	no	Linked Event subcategory. Requires `category` or `categories`.
`domain`	no	Deprecated legacy linked CAMEO+ domain filter. Prefer `category` for new integrations.
`has_fatalities`	no	Filter to Entities linked to fatal Event evidence.
`civilian_targeting`	no	Filter to Entities linked to Conflict evidence where civilians are the primary target.
`sort`	no	`significance` default, or `recent` for latest linked evidence.
`limit`	no	Number of Entity cards, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.
`include_images`	no	Keep Wikipedia thumbnail/avatar URLs on Entity cards when available. Default `true`.

`get_entity`

Parameter	Required	Description
`entity_id`	yes	Known Entity ID returned by `search_entities`, Event refs, or Story refs.
`start_date`	no	Inclusive start date for linked references, max 30-day window.
`end_date`	no	Inclusive end date for linked references, max 30-day window.
`days`	no	Window size, 1-30. Default 30.
`limit`	no	Linked Story/Event references to include, 1-50. Default 10.
`include_images`	no	Keep Wikipedia thumbnail/avatar URLs on the Entity profile when available. Default `true`.

`list_admin1`

Parameter	Required	Description
`country`	yes	One plain English country name. ISO-3 and legacy FIPS aliases are accepted.

Energy Data Tools

Use Energy tools for Global Energy Monitor registry questions: capacity, status, asset location, ownership, parent entities, and cross-tracker owner portfolios. Energy registry facts are structural; pair them with Events or Stories only when the user asks how current developments affect physical infrastructure.

`energy_search_owners`

Resolve a company, ministry, state owner, person, or investment vehicle to a canonical GEM Entity ID before portfolio analysis.

Parameter	Required	Description
`q`	no	Search GEM ownership entities by name, abbreviation, GEM Entity ID, or external ID.
`entity_id`	no	Exact GEM Entity ID lookup.
`country`	no	One or more country names or ISO-3 codes; matches registration or headquarters country.
`region`	no	Region filter over registration or headquarters country.
`continent`	no	Continent filter over registration or headquarters country.
`entity_type`	no	One or more GEM owner entity types, such as `company`, `government`, or `person`.
`publicly_listed`	no	Filter to publicly listed or non-listed owner entities.
`limit`	no	Owner records per page, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.

`energy_get_owner`

Fetch one GEM ownership entity by entity_id, including registration/headquarters metadata, parent GEM entities, external IDs, source metadata, and a portfolio summary across energy assets.

Parameter	Required	Description
`entity_id`	yes	GEM Entity ID returned by `energy_search_owners` or asset owner arrays.
`include_exposure`	no	Request admin-gated exposure summaries from the risk/exposure preview. Non-admin callers receive a 403 from the API.

`energy_assets_by_owner`

Pivot from a GEM Entity ID to every asset where that entity appears in owners, operators, or parents arrays.

Parameter	Required	Description
`owner_entity_id`	yes	GEM Entity ID. Use `energy_search_owners` first when the ID is unknown.
`country` / `region` / `continent`	no	Optional geography filters over the returned portfolio.
`tracker`	no	Optional tracker filter, such as `coal_plants`, `coal_mines`, `wind`, or `nuclear`.
`status`	no	Optional asset-status filter.
`operating_only`	no	When true, keeps operating assets.
`limit`	no	Maximum asset rows.

Facilities Data Tools

Use Facilities tools for the unified physical-asset directory — GEM energy assets, World Port Index ports, and Epoch AI data centers on one keyed surface, each resolved to its owner entities on the spine. Answer “what facilities of type X exist in country Y”, “what does operator Z own”, or “which facilities sit near this event” (bbox / near). Plan-gated: the underlying /api/v2/facilities routes require the can_use_facilities entitlement (Analyst plan and up) and otherwise return 403 PLAN_REQUIRED.

`facilities_search`

Search the directory by name, type/class, source silo, geography, owner, status, and capacity.

Parameter	Required	Description
`q`	no	Case-insensitive substring match on the facility name.
`type`	no	One or more leaf facility types (`coal_plant`, `oil_gas_plant`, `nuclear_plant`, `geothermal_plant`, `bioenergy_plant`, `hydropower_plant`, `solar_farm`, `wind_farm`, `coal_mine`, `oil_gas_field`, `coal_terminal`, `lng_terminal`, `gas_pipeline`, `oil_pipeline`, `lng_carrier`, `port`, `data_center`).
`facility_class`	no	Coarse class: `power`, `extraction`, `transport_logistics`, `digital_infrastructure`.
`source`	no	Source silo(s): `gem`, `maritime_ports`, `epoch`.
`country` / `region` / `continent`	no	Geography filters (same semantics as `search_events`).
`owner_entity_id`	no	Spine entity_id (`e_...`) — facilities this entity owns.
`owner_search`	no	Case-insensitive substring match on the owner name.
`status`	no	Operating-status value(s): `operating`, `construction`, `proposed`, `retired`, …
`capacity_mw_min` / `capacity_mw_max`	no	Capacity bounds in MW (power facilities + data centers).
`has_geo` / `has_owner`	no	Restrict to facilities with coordinates / with a resolved spine owner.
`bbox`	no	Geographic viewport `lat_min,lon_min,lat_max,lon_max`.
`near`	no	Proximity `lat,lon,radius_km`.
`sort`	no	`name` (default), `capacity_desc`, `capacity_asc`, `recent`, `country`.
`limit`	no	Cards per page, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.

`facilities_get`

Fetch one facility by its stable facility_id, including source attributes, owners (with spine entity_ids), and reversible cross-silo merge history.

Parameter	Required	Description
`facility_id`	yes	The `f_...` id from a `facilities_search` card.

`facilities_by_owner`

Pivot from a spine entity_id to every facility that entity owns across all silos — the owner → portfolio join.

Parameter	Required	Description
`owner_entity_id`	yes	Spine entity_id (`e_...`). Resolve a name via `unified_entity_search`.
`type`	no	Optionally scope the portfolio to one or more facility types.
`country` / `region` / `continent`	no	Optional geography filters over the portfolio.
`has_geo`	no	When true, only mappable facilities (with coordinates).
`sort`	no	Facility sort order (default `capacity_desc`).
`limit`	no	Maximum facility rows.

Monitoring Briefs

A Monitoring Brief is a short, source-backed memo answering What changed? Why does it matter? What evidence supports it? What should I watch next? — quantified against a baseline and grounded in clickable GDELT Cloud evidence.

Brief tools are plan-gated. create_brief, list_briefs, and get_brief require a plan with Briefs access (can_use_briefs). On a plan without it these tools are hidden from the tool list and any call returns a BRIEF_ACCESS_DENIED error; once a plan’s included Brief runs are used up, create_brief returns BRIEF_LIMIT_REACHED. Brief runs are metered separately and do not consume the plan’s query-unit quota.

`create_brief`

Create and kick off a Monitoring Brief. Non-blocking — returns immediately while the agent runs (~5–10 minutes); poll get_brief(brief_id) for status and content.

Parameter	Required	Description
`scope_text`	yes	One or two plain sentences: the situation, where it is, who/what is affected, and the decision it informs.
`time_window`	no	Recent window analysed: `6h`, `24h`, `72h`, `7d`, or `30d`. Default `24h`.
`baseline_window`	no	Earlier comparison window for change detection: `7d`, `14d`, or `30d`. Default `14d`.
`audience`	no	Framing/length: `executive` (default), `analyst`, or `operator`.
`depth`	no	Density: `skim`, `standard` (default), or `detailed`.
`countries`	no	ISO-3 country codes to scope the Brief, e.g. `["YEM","SAU"]`.
`regions`	no	Region names to scope the Brief.
`sectors`	no	Business/mission sectors to emphasise.
`public_link`	no	When `true`, also mint a public, shareable report URL. Default `false` (private).
`title`	no	Optional title; auto-generated from `scope_text` if omitted.

{
  "tool_name": "create_brief",
  "tool_arguments": {
    "scope_text": "Monitor Red Sea maritime disruption risk to shipping across Yemen, the Red Sea, and the Gulf of Aden.",
    "time_window": "7d",
    "baseline_window": "30d",
    "audience": "executive",
    "countries": ["YEM", "SAU"]
  }
}

Returns the new Brief id, status (queued), title, and report URLs.

`list_briefs`

List the caller’s Monitoring Briefs with status and basic metadata (id, title, status, created_at, report URLs). No parameters.

`get_brief`

Fetch one Brief: status, the structured JSON document, citations, the evidence appendix, and report URLs.

Parameter	Required	Description
`brief_id`	yes	The Brief id returned by `create_brief` or `list_briefs`.

Statuses progress queued → generating → building → ready (or failed).

Response Objects

gdelt_cloud_tool_call returns an MCP call result whose structured content is the same REST-shaped response object returned by the selected v2 API endpoint. List tools return success, data, and pagination; detail tools return one data object; summary tools return group_by and summary buckets.

Event card

Returned by search_events and get_event.

{
  "success": true,
  "data": [
    {
      "id": "conflict_20260417_example",
      "url": "https://gdeltcloud.com/story/example-story",
      "primary_story_url": "https://gdeltcloud.com/story/example-story",
      "family": "conflict",
      "title": "Example event title",
      "summary": "Short generated event summary.",
      "image_url": "https://example.com/source-image.jpg",
      "event_date": "2026-04-17",
      "category": "Protests",
      "subcategory": "Peaceful protest",
      "domain": "CONFLICT",
      "event_code": "ACLED-123",
      "geo": {
        "country": "France",
        "region": "Europe",
        "continent": "Europe",
        "admin1": "Ile-de-France",
        "location": "Paris",
        "latitude": 48.8566,
        "longitude": 2.3522
      },
      "geo_context": {
        "location_country": "France",
        "actor_origin_countries": ["France"]
      },
      "actors": [
        {
          "name": "Protesters",
          "country": "France",
          "role": "actor1"
        }
      ],
      "metrics": {
        "significance": 0.72,
        "goldstein_scale": -2,
        "magnitude": null,
        "systemic_importance": null,
        "propagation_potential": null,
        "market_sensitivity": null,
        "confidence": 0.91,
        "article_count": 4
      },
      "has_fatalities": false,
      "fatalities": 0,
      "story_refs": [
        {
          "id": "story_20260417_example",
          "url": "https://gdeltcloud.com/story/example-story",
          "title": "Example story",
          "story_date": "2026-04-17",
          "article_count": 4
        }
      ],
      "entity_refs": [
        {
          "id": "Paris",
          "name": "Paris",
          "type": "LOCATION",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Paris",
          "image_url": "https://upload.wikimedia.org/paris.jpg",
          "avatar_url": "https://upload.wikimedia.org/paris.jpg"
        }
      ],
      "top_articles": [
        {
          "url": "https://example.com/article",
          "title": "Example article",
          "domain": "example.com",
          "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.com&sz=64",
          "image_url": "https://example.com/source-image.jpg",
          "rank": 1
        }
      ]
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": "25"
  }
}

Field	Description
`id`	Stable v2 Event identifier.
`url`, `primary_story_url`	Public GDELT Cloud Story URL for citation when the Event has a linked Story.
`family`	`conflict` or `cameoplus`.
`title`, `summary`, `event_date`	Generated Event headline, summary, and date.
`image_url`	First available top-article sharing image promoted to the Event card.
`category`, `subcategory`, `domain`, `event_code`	Product taxonomy and source/generated code fields.
`geo`	Primary Event location with `country`, `region`, `continent`, `admin1`, `location`, `latitude`, and `longitude`.
`geo_context`	Shows the location country and actor-origin countries that explain broad geo matches.
`actors`	Event actors with `name`, normalized `country`, and `role`.
`metrics`	Event significance plus Goldstein, CAMEO+, confidence, and article evidence metrics.
`has_fatalities`, `fatalities`	Fatality flag and count.
`civilian_targeting`, `civilian_targeting_label`	Conflict civilian-targeting flag and ACLED label.
`story_refs`, `entity_refs`, `top_articles`	Linked Story, linked Entity, and top 3 source article evidence. Entity refs may include `image_url`/`avatar_url`; article refs may include `domain_avatar_url` and `image_url`.

Story card

Returned by search_stories and get_story.

{
  "success": true,
  "data": {
    "id": "story_20260417_example",
    "url": "https://gdeltcloud.com/story/example-story",
    "title": "Example story title",
    "image_url": "https://example.com/source-image.jpg",
    "story_date": "2026-04-17",
    "category": "infrastructure",
    "subcategory": null,
    "geo": {
      "country": "Japan",
      "region": "East Asia",
      "continent": "Asia",
      "admin1": "Tokyo",
      "location": "Tokyo",
      "latitude": 35.6762,
      "longitude": 139.6503
    },
    "geo_context": {
      "location_country": "Japan",
      "actor_origin_countries": ["Japan", "United States"]
    },
    "metrics": {
      "significance": 0.82,
      "article_count": 12,
      "linked_event_count": 2,
      "max_linked_event_significance": 0.76
    },
    "has_events": true,
    "has_fatalities": false,
    "fatalities": 0,
    "linked_events": [
      {
        "id": "cameoplus_20260417_example",
        "title": "Example linked Event"
      }
    ],
    "entity_refs": [
      {
        "id": "Tokyo",
        "name": "Tokyo",
        "type": "LOCATION",
        "wikipedia_url": "https://en.wikipedia.org/wiki/Tokyo",
        "image_url": "https://upload.wikimedia.org/tokyo.jpg",
        "avatar_url": "https://upload.wikimedia.org/tokyo.jpg"
      }
    ],
    "top_articles": [
      {
        "url": "https://example.com/article",
        "title": "Example article",
        "domain": "example.com",
        "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.com&sz=64",
        "image_url": "https://example.com/source-image.jpg",
        "rank": 1
      }
    ]
  }
}

Field	Description
`id`, `url`	Stable Story id and public GDELT Cloud Story URL.
`title`, `story_date`	Cluster headline and date.
`image_url`	First available top-article sharing image promoted to the Story card.
`category`, `subcategory`	Story and linked-Event taxonomy context.
`geo`, `geo_context`	Primary linked-Event geography and actor-origin countries.
`metrics`	Story significance, article count, linked Event count, and max linked Event significance.
`has_events`, `linked_events`	Whether structured Events link to the Story and up to 10 linked Event refs.
`has_fatalities`, `fatalities`	Whether linked Events include fatalities, plus total linked fatalities.
`entity_refs`, `top_articles`	Linked Entities and top 3 source articles, with optional Entity thumbnails, article images, and domain avatars.

Event summary bucket

Returned by summarize_events.

{
  "success": true,
  "group_by": "country",
  "data": [
    {
      "key": "France",
      "group_by": "country",
      "event_count": 12,
      "conflict_event_count": 4,
      "cameoplus_event_count": 8,
      "fatality_event_count": 2,
      "fatalities": 6,
      "fatality_event_rate": 0.1667,
      "country_count": 1,
      "region_count": 1,
      "article_count": 40,
      "avg_article_count": 3.333,
      "min_article_count": 1,
      "max_article_count": 12,
      "avg_significance": 0.42,
      "max_significance": 0.91,
      "min_significance": 0.05,
      "avg_goldstein_scale": -3.8,
      "metrics": {
        "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 },
        "goldstein_scale": { "avg": -3.8, "min": -8, "max": 2, "avg_severity": 4.2 },
        "goldstein_severity": { "avg": 4.2, "min": 0.5, "max": 8 },
        "cameoplus": {
          "magnitude": { "avg": 6.1, "min": 1.2, "max": 9 },
          "systemic_importance": { "avg": 0.52, "min": 0.11, "max": 0.9 },
          "propagation_potential": { "avg": 0.47, "min": 0.07, "max": 0.81 },
          "market_sensitivity": { "avg": 0.31, "min": 0.03, "max": 0.75 }
        },
        "confidence": { "avg": 0.83, "min": 0.44, "max": 0.98 },
        "article_count": { "total": 40, "avg": 3.333, "min": 1, "max": 12 },
        "fatalities": { "events": 2, "rate": 0.1667, "total": 6 }
      },
      "metric_stats": {
        "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 }
      }
    }
  ]
}

Story summary bucket

Returned by summarize_stories.

{
  "success": true,
  "group_by": "date",
  "data": [
    {
      "key": "2026-04-17",
      "group_by": "story_date",
      "story_count": 5,
      "article_count": 25,
      "avg_article_count": 5,
      "min_article_count": 2,
      "max_article_count": 11,
      "stories_with_events": 4,
      "story_only_count": 1,
      "linked_event_count": 7,
      "min_linked_event_count": 0,
      "avg_linked_event_count": 1.4,
      "max_linked_event_count": 3,
      "stories_with_fatalities": 1,
      "fatalities": 2,
      "fatality_story_rate": 0.2,
      "avg_significance": 0.5,
      "max_significance": 0.88,
      "min_significance": 0.12,
      "metrics": {
        "significance": { "avg": 0.5, "max": 0.88, "min": 0.12 },
        "article_count": { "total": 25, "avg": 5, "min": 2, "max": 11 },
        "linked_events": {
          "count": { "total": 7, "avg": 1.4, "min": 0, "max": 3, "stories_with_events": 4, "story_only_count": 1 },
          "significance": { "avg": 0.62, "min": 0.18, "max": 0.94 },
          "goldstein_scale": { "avg": -3.2, "min": -7.5, "max": 1.5, "avg_severity": 3.8 },
          "goldstein_severity": { "avg": 3.8, "min": 0.8, "max": 7.5 },
          "magnitude": { "avg": 5.5, "min": 1.1, "max": 8.4 },
          "systemic_importance": { "avg": 0.44, "min": 0.12, "max": 0.77 },
          "propagation_potential": { "avg": 0.41, "min": 0.09, "max": 0.72 },
          "market_sensitivity": { "avg": 0.39, "min": 0.04, "max": 0.68 },
          "confidence": { "avg": 0.81, "min": 0.51, "max": 0.96 }
        },
        "recency_score": { "avg": 1 },
        "fatalities": { "stories": 1, "rate": 0.2, "total": 2 }
      },
      "metric_stats": {
        "significance": { "avg": 0.5, "max": 0.88, "min": 0.12 }
      }
    }
  ]
}

Summary field	Description
`key`, `group_by`	Bucket value and concrete grouping label.
`event_count`, `story_count`	Number of Events or Stories in the bucket.
`conflict_event_count`, `cameoplus_event_count`	Event-family counts.
`article_count`, `avg_article_count`, `min_article_count`, `max_article_count`	Evidence volume.
`fatality_event_count`, `stories_with_fatalities`, `fatalities`, rates	Fatality coverage.
`country_count`, `region_count`	Distinct geography counts represented in the bucket.
`stories_with_events`, `story_only_count`	Story buckets split by whether they link to one or more structured Events.
`linked_event_count`, `min_linked_event_count`, `avg_linked_event_count`, `max_linked_event_count`	Story-to-Event link coverage for Story buckets. This is not a distinct Event total.
`metrics`, `metric_stats`	Nested aggregate statistics; `metric_stats` is an alias of `metrics`.

Articles, Entities, Admin1, And Standard error

get_story_articles returns Article objects with id, url, title, domain, article_date, rank, and role, plus pagination. search_entities returns Entity cards with id, url, name, type, wikipedia_url, and metrics. get_entity adds story_refs, event_refs, and admin-gated entity_tone when requested by API clients. list_admin1 returns success, normalized country, an admin1 array, and source. Energy owner tools return GEM ownership records with entity_id, name, registration/headquarters fields, parent IDs, external IDs, portfolio_url, detail_url, and portfolio_summary. energy_get_owner(include_exposure=true) can also include admin-gated exposure summaries.

{
  "success": false,
  "error": "Invalid continent. Use one of: Africa, Asia, Europe, North America, South America, Oceania",
  "code": "INVALID_CONTINENT",
  "details": {
    "param": "continent",
    "invalid_value": "Atlantis",
    "accepted_values": ["Africa", "Asia", "Europe", "North America", "South America", "Oceania"],
    "example": "?continent=Asia"
  }
}

Category/subcategory validation errors include accepted_values, nearest_values when practical, and a corrected example so agents can recover in the next call. A subcategory without its parent category returns a compact parent-required error.

Output Notes

Country output is plain English.
Geo output includes country, region, continent, admin1, location, latitude, and longitude when available.
Event geography filters match location country or actor-origin country. Dashboard clients should compare geo.location_country and geo_context.actor_origin_countries to label a result as a location match, actor match, or both.
Event and Story cards include top 3 inline articles.
Full Story article lists are paginated through get_story_articles.
metrics.goldstein_scale is the only public Goldstein metric on Event cards. It is present for Conflict Events and CAMEO+ POLITICAL Events where meaningful, and null for non-political CAMEO+ Events.
CAMEO+ detail metric filters (magnitude, systemic_importance, propagation_potential, market_sensitivity) only match scored CAMEO+ Events. significance and confidence are cross-family filters.
Those four are rubric scores — the coder reads concrete sub-factors off the source text and a fixed published formula turns them into the value. Read them as ordinal ranking signals, not measurements, probabilities, or predicted price moves. magnitude is comparable within a domain only and is null when no severity observable was found (null means unknown, never 0).
Event significance is a family-scoped weighted blend, renormalized so every family spans a true 0–1: each event’s raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count, saturating around 100 deaths), civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured, both its term and its 0.20 weight are dropped.
Default ranking is canonical significance; use recent when freshness matters more than importance.

Overview

Tools

Resources

Skills

Prompts

Integrations

GDELT Cloud v2 MCP Tools

Overview

Wrapper Parameters

Shared Date Parameters

`search_events`

`summarize_events`

`get_event`

`search_stories`

`summarize_stories`

`get_story`

`get_story_articles`

`search_entities`

`get_entity`

`list_admin1`

Energy Data Tools

`energy_search_owners`

`energy_get_owner`

`energy_assets_by_owner`

Facilities Data Tools

`facilities_search`

`facilities_get`

`facilities_by_owner`

Monitoring Briefs

`create_brief`

`list_briefs`

`get_brief`

Response Objects

Event card

Story card

Event summary bucket

Story summary bucket

Articles, Entities, Admin1, And Standard error

Output Notes

​Overview

​Wrapper Parameters

​Shared Date Parameters

​search_events

​summarize_events

​get_event

​search_stories

​summarize_stories

​get_story

​get_story_articles

​search_entities

​get_entity

​list_admin1

​Energy Data Tools

​energy_search_owners

​energy_get_owner

​energy_assets_by_owner

​Facilities Data Tools

​facilities_search

​facilities_get

​facilities_by_owner

​Monitoring Briefs

​create_brief

​list_briefs

​get_brief

​Response Objects

​Event card

​Story card

​Event summary bucket

​Story summary bucket

​Articles, Entities, Admin1, And Standard error

​Output Notes

Overview

Wrapper Parameters

Shared Date Parameters

`search_events`

`summarize_events`

`get_event`

`search_stories`

`summarize_stories`

`get_story`

`get_story_articles`

`search_entities`

`get_entity`

`list_admin1`

Energy Data Tools

`energy_search_owners`

`energy_get_owner`

`energy_assets_by_owner`

Facilities Data Tools

`facilities_search`

`facilities_get`

`facilities_by_owner`

Monitoring Briefs

`create_brief`

`list_briefs`

`get_brief`

Response Objects

Event card

Story card

Event summary bucket

Story summary bucket

Articles, Entities, Admin1, And Standard error

Output Notes