GDELT Cloud Documentation - Global News Event Analytics API

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

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 and Story list/summary tools default to confidence_profile=precise for analyst-ready, non-repetitive results. Use confidence_profile=loose only when the task explicitly needs exhaustive/raw retrieval. Detail tools (get_event, get_story, and Story articles) remain exhaustive by ID.

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_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.

`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	`conflict` or `cameoplus`.
`category`	no	Single product category enum, such as `Protests` or a CAMEO+ domain.
`categories`	no	Multi-select product categories. Values are OR’d together and serialized to the API as `category=Protests,CRIME`.
`subcategory`	no	Specific Event subtype, code, or description.
`domain`	no	CAMEO+ domain: `POLITICAL`, `ECONOMIC`, `CORPORATE`, `TECHNOLOGY`, `INFRASTRUCTURE`, `HEALTH`, `INFORMATION`, `ENVIRONMENT`, `CRIME`.
`search`	no	Semantic search text; not a keyword-only filter.
`has_fatalities`	no	Boolean fatality filter.
`confidence_profile`	no	`strictest`, `precise` default, `balanced`, or `loose`. Default `precise` requires Event confidence >= 0.75 and linked primary/strong Story evidence. Use `loose` for exhaustive/raw retrieval.
`min_confidence`	no	Event confidence threshold override, 0-1. Overrides the Event threshold implied by `confidence_profile`.
`sort`	no	`significance` default, or `recent`.
`limit`	no	Number of Event cards, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.

{
  "tool_name": "search_events",
  "tool_arguments": {
    "event_family": "cameoplus",
    "domain": "INFRASTRUCTURE",
    "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.

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	`conflict` or `cameoplus`.
`category`	no	Single product category enum.
`categories`	no	Multi-select product categories. Values are OR’d together and serialized to the API as comma-separated `category`.
`subcategory`	no	Event subtype, code, or description.
`domain`	no	CAMEO+ domain.
`has_fatalities`	no	Boolean fatality filter.
`confidence_profile`	no	`strictest`, `precise` default, `balanced`, or `loose`. Default `precise` requires Event confidence >= 0.75 and linked primary/strong Story evidence. Use `loose` for exhaustive/raw rollups.
`min_confidence`	no	Event confidence threshold override, 0-1. Overrides the Event threshold implied by `confidence_profile`.
`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.

`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	Story cluster category.
`event_category`	no	Single linked Event top-level category, such as `Protests`, `POLITICAL`, or `CRIME`.
`event_categories`	no	Multi-select linked Event categories. Values are OR’d together and serialized to the API as `event_category=Protests,CRIME`.
`subcategory`	no	Linked-Event subcategory/code/description.
`domain`	no	Linked CAMEO+ domain.
`search`	no	Semantic search text; not a keyword-only filter.
`has_events`	no	Boolean filter for Stories with linked structured Events.
`has_fatalities`	no	Boolean filter for Stories linked to fatal Events.
`confidence_profile`	no	`strictest`, `precise` default, `balanced`, or `loose`. Default `precise` keeps primary/strong Story families and collapses obvious duplicates before pagination. Use `loose` for exhaustive/raw retrieval.
`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`.

`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.

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	Story cluster category.
`event_category`	no	Single linked Event top-level category, such as `Protests`, `POLITICAL`, or `CRIME`.
`event_categories`	no	Multi-select linked Event categories. Values are OR’d together and serialized to the API as comma-separated `event_category`.
`subcategory`	no	Linked-Event subcategory/code/description.
`domain`	no	Linked CAMEO+ domain.
`has_events`	no	Boolean linked-Event filter.
`has_fatalities`	no	Boolean linked-fatality filter.
`confidence_profile`	no	`strictest`, `precise` default, `balanced`, or `loose`. Default `precise` keeps primary/strong Story families and collapses obvious duplicates before aggregation. Use `loose` for exhaustive/raw rollups.
`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.

`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`.

`search_entities`

Parameter	Required	Description
`search`	no	Entity name search string.
`type`	no	`person`, `organization`, or `location`.
`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.
`limit`	no	Number of Entity cards, 1-100. Default 25.
`cursor`	no	Pagination cursor from `pagination.next_cursor`.

`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.

`list_admin1`

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

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.",
      "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"
        }
      ],
      "top_articles": [
        {
          "url": "https://example.com/article",
          "title": "Example article",
          "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.
`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.
`story_refs`, `entity_refs`, `top_articles`	Linked Story, linked Entity, and top 3 source article evidence.

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",
    "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"
      }
    ],
    "top_articles": [
      {
        "url": "https://example.com/article",
        "title": "Example article",
        "domain": "example.com",
        "rank": 1
      }
    ]
  }
}

Field	Description
`id`, `url`	Stable Story id and public GDELT Cloud Story URL.
`title`, `story_date`	Cluster headline and date.
`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.

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 and event_refs. list_admin1 returns success, normalized country, an admin1 array, and source.

{
  "success": false,
  "error": "Invalid continent. Use one of: Africa, Asia, Europe, North America, South America, Oceania",
  "code": "INVALID_CONTINENT"
}

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.
Event significance uses: Goldstein severity 25% + CAMEO+ magnitude 20% + systemic importance 15% + propagation potential 10% + market sensitivity 10% + fatalities 10% + article evidence 5% + confidence 5%.
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`

Response Objects

Event card

Story card

Event summary bucket

Story summary bucket

Articles, Entities, Admin1, And Standard error

Output Notes

Overview

Tools

Resources

Skills

Prompts

Integrations

Documentation Index

​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

​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`

Response Objects

Event card

Story card

Event summary bucket

Story summary bucket

Articles, Entities, Admin1, And Standard error

Output Notes