GDELT CloudGDELT Cloud
Agent World-State API

Give AI agents machine-readable external world state.

Connect agents to queryable Events, Stories, Entities, summaries, and geographic discovery so they can reason over changing world state instead of searching raw news from scratch.

Tutorial path
Agent task

Ask an agent to monitor Lebanon conflict events with fatalities, summarize the most significant Events and linked Stories, and flag changes that matter for regional exposure.

1
Connect the API and MCP surfaces

Your job can call REST directly, and your agent can call the same product data through MCP.

2
Probe the Event shape or inspect MCP schemas

You know the Event card shape and the MCP tools the agent should use.

3
Monitor Lebanon conflict Events

The monitor returns structured conflict records sorted by significance.

4
Pull linked Story evidence

The agent has Story clusters, linked Events, Entities, and top article evidence.

REST API and MCP, side by side

A working Hello World path from query to product surface.

Each step shows the deterministic REST call and the agent-native MCP equivalent using the current progressive discovery wrapper.

  1. Step 1

    Connect the API and MCP surfaces

    Set up the same credential for deterministic REST calls and agent-native MCP calls.

    Your job can call REST directly, and your agent can call the same product data through MCP.
    REST client setup
    python
    import os
import httpx

API_KEY = os.environ["GDELT_API_KEY"]

client = httpx.Client(
    base_url="https://gdeltcloud.com",
    timeout=30,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Accept": "application/json",
    },
)
    Expected setup result
    text
    No product query runs in this step.
The credential is now available to both REST and MCP calls.
  2. Step 2

    Probe the Event shape or inspect MCP schemas

    Before asking an agent to monitor anything, check the returned fields and the exact tool contract.

    You know the Event card shape and the MCP tools the agent should use.
    REST shape probe
    python
    params = {
    "country": "Lebanon",
    "event_family": "conflict",
    "sort": "significance",
    "limit": 1,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
event_probe = r.json()
    Representative list response
    json
    {
  "success": true,
  "data": [
    {
      "id": "conflict_lebanon_001",
      "url": "https://gdeltcloud.com/events/border-area-conflict-event-with-linked-story-evidence--conflict_lebanon_001",
      "primary_story_url": "https://gdeltcloud.com/stories/cross-border-escalation-story-cluster-storyleb",
      "family": "conflict",
      "title": "Border-area conflict event with linked story evidence",
      "summary": "Structured conflict event card with linked Story evidence and source articles.",
      "event_date": "2026-05-07",
      "category": "Explosions/Remote violence",
      "subcategory": "Shelling/artillery/missile attack",
      "domain": "CONFLICT",
      "event_code": "conflict_source_001",
      "geo": {
        "country": "Lebanon",
        "region": "Middle East",
        "continent": "Asia",
        "admin1": "South Governorate",
        "location": "southern border area",
        "latitude": 33.2721,
        "longitude": 35.2033
      },
      "geo_context": {
        "location_country": "Lebanon",
        "actor_origin_countries": [
          "Lebanon",
          "Israel"
        ]
      },
      "actors": [
        {
          "name": "Armed group",
          "country": "Lebanon",
          "role": "actor1"
        },
        {
          "name": "Military forces",
          "country": "Israel",
          "role": "actor2"
        }
      ],
      "metrics": {
        "significance": 0.84,
        "goldstein_scale": null,
        "magnitude": null,
        "systemic_importance": null,
        "propagation_potential": null,
        "market_sensitivity": null,
        "confidence": 0.91,
        "article_count": 18
      },
      "has_fatalities": false,
      "fatalities": 0,
      "story_refs": [
        {
          "id": "story_lebanon_border_001",
          "url": "https://gdeltcloud.com/stories/cross-border-escalation-story-cluster-storyleb",
          "title": "Cross-border escalation story cluster",
          "story_date": "2026-05-07",
          "article_count": 18
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Hezbollah",
          "name": "Hezbollah",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Hezbollah",
          "image_url": null,
          "avatar_url": null
        }
      ],
      "top_articles": [
        {
          "url": "https://example.org/source-article",
          "title": "Representative source article",
          "domain": "example.org",
          "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.org&sz=64",
          "rank": 1,
          "image_url": null
        }
      ],
      "image_url": null
    }
  ],
  "pagination": {
    "limit": 1,
    "cursor": null,
    "next_cursor": null
  },
  "sort": "significance"
}
  3. Step 3

    Monitor Lebanon conflict Events

    Pull a small, high-signal Event set that an agent can reason over without reading raw news.

    The monitor returns structured conflict records sorted by significance.
    REST Event monitor
    python
    params = {
    "country": "Lebanon",
    "event_family": "conflict",
    "has_fatalities": True,
    "sort": "significance",
    "limit": 10,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
events = r.json()["data"]
    Representative Event monitor output
    json
    {
  "success": true,
  "data": [
    {
      "id": "conflict_lebanon_002",
      "url": "https://gdeltcloud.com/events/high-significance-conflict-event-with-reported-fatalities--conflict_lebanon_002",
      "primary_story_url": "https://gdeltcloud.com/stories/cross-border-escalation-story-cluster-storyleb",
      "family": "conflict",
      "title": "High-significance conflict event with reported fatalities",
      "summary": "A high-significance conflict Event linked to a Story cluster and source evidence.",
      "event_date": "2026-05-07",
      "category": "Explosions/Remote violence",
      "subcategory": "Shelling/artillery/missile attack",
      "domain": "CONFLICT",
      "event_code": "conflict_source_002",
      "geo": {
        "country": "Lebanon",
        "region": "Middle East",
        "continent": "Asia",
        "admin1": "South Governorate",
        "location": "southern border area",
        "latitude": 33.2721,
        "longitude": 35.2033
      },
      "geo_context": {
        "location_country": "Lebanon",
        "actor_origin_countries": [
          "Lebanon",
          "Israel"
        ]
      },
      "actors": [
        {
          "name": "Armed group",
          "country": "Lebanon",
          "role": "actor1"
        },
        {
          "name": "Military forces",
          "country": "Israel",
          "role": "actor2"
        }
      ],
      "metrics": {
        "significance": 0.88,
        "goldstein_scale": null,
        "magnitude": null,
        "systemic_importance": null,
        "propagation_potential": null,
        "market_sensitivity": null,
        "confidence": 0.92,
        "article_count": 21
      },
      "has_fatalities": true,
      "fatalities": 2,
      "story_refs": [
        {
          "id": "story_lebanon_border_002",
          "url": "https://gdeltcloud.com/stories/cross-border-escalation-story-cluster-storyleb",
          "title": "Cross-border escalation story cluster",
          "story_date": "2026-05-07",
          "article_count": 21
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Hezbollah",
          "name": "Hezbollah",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Hezbollah",
          "image_url": null,
          "avatar_url": null
        }
      ],
      "top_articles": [
        {
          "url": "https://example.org/source-article",
          "title": "Representative source article",
          "domain": "example.org",
          "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.org&sz=64",
          "rank": 1,
          "image_url": null
        }
      ],
      "image_url": null
    }
  ],
  "pagination": {
    "limit": 10,
    "cursor": null,
    "next_cursor": null
  },
  "sort": "significance"
}
  4. Step 4

    Pull linked Story evidence

    Move from structured incidents to narrative clusters and source articles the agent can cite.

    The agent has Story clusters, linked Events, Entities, and top article evidence.
    REST Story evidence
    python
    params = {
    "country": "Lebanon",
    "has_events": True,
    "has_fatalities": True,
    "sort": "significance",
    "limit": 5,
}

r = client.get("/api/v2/stories", params=params)
r.raise_for_status()
stories = r.json()["data"]
    Representative Story evidence output
    json
    {
  "success": true,
  "data": [
    {
      "id": "story_lebanon_border_002",
      "url": "https://gdeltcloud.com/stories/cross-border-escalation-story-cluster-storyleb",
      "title": "Cross-border escalation story cluster",
      "story_date": "2026-05-07",
      "category": "conflict_security",
      "subcategory": null,
      "geo": {
        "country": "Lebanon",
        "region": "Middle East",
        "continent": "Asia",
        "admin1": "South Governorate",
        "location": "southern border area",
        "latitude": 33.2721,
        "longitude": 35.2033
      },
      "geo_context": {
        "location_country": "Lebanon",
        "actor_origin_countries": [
          "Lebanon",
          "Israel"
        ]
      },
      "metrics": {
        "significance": 0.79,
        "article_count": 21,
        "linked_event_count": 3,
        "max_linked_event_significance": 0.88
      },
      "has_events": true,
      "has_fatalities": true,
      "fatalities": 2,
      "linked_events": [
        {
          "id": "conflict_lebanon_002",
          "title": "High-significance conflict event with reported fatalities"
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Hezbollah",
          "name": "Hezbollah",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Hezbollah",
          "image_url": null,
          "avatar_url": null
        }
      ],
      "top_articles": [
        {
          "url": "https://example.org/source-article",
          "title": "Representative source article",
          "domain": "example.org",
          "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.org&sz=64",
          "rank": 1,
          "image_url": null
        }
      ],
      "image_url": null
    }
  ],
  "pagination": {
    "limit": 5,
    "cursor": null,
    "next_cursor": null
  },
  "sort": "significance"
}

Workflow fit

Agents that monitor a country, actor, sector, or issue domain.

Research copilots that cite structured Events and linked Story evidence.

Automated briefs that combine GDELT Cloud signals with your internal workflow.

Output widgets

Event monitor
10

Highest-significance conflict Events returned for the current Lebanon monitor window.

Story evidence
5

Linked story clusters retained so agent conclusions stay source-backed.

Agent surface
MCP

The same product data can be called through a tool-aware agent runtime.