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.

Connect the API and MCP surfaces

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

Probe the Event shape or inspect MCP schemas

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

Monitor Lebanon conflict Events

The monitor returns structured conflict records sorted by significance.

Pull linked Story evidence

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

Pivot to physical energy-infrastructure exposure

The agent now has a capacity-weighted energy mix for the country plus the specific operating assets within a proximity radius — feed both into a downstream brief or risk model.

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.

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",
    },
)

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",
    },
)

MCP server setup

json

{
  "mcp_servers": {
    "gdelt-cloud": {
      "url": "https://gdelt-cloud-mcp.fastmcp.app/mcp",
      "auth": "bearer",
      "env": {
        "GDELT_API_KEY": "gdelt_sk_..."
      }
    }
  }
}

Expected setup result

text

No product query runs in this step.
The credential is now available to both REST and MCP calls.

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",
    "category": "Battles",
    "subcategory": "Armed clash",
    "sort": "significance",
    "limit": 1,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
event_probe = r.json()

REST shape probe

python

params = {
    "country": "Lebanon",
    "category": "Battles",
    "subcategory": "Armed clash",
    "sort": "significance",
    "limit": 1,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
event_probe = r.json()

MCP schema discovery

json

{
  "tool": "gdelt_cloud_tool_get",
  "arguments": {
    "tool_names": ["search_events", "search_stories"]
  }
}

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"
}

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",
    "category": "Battles,Explosions/Remote violence,Violence against civilians",
    "has_fatalities": True,
    "sort": "significance",
    "limit": 10,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
events = r.json()["data"]

REST Event monitor

python

params = {
    "country": "Lebanon",
    "category": "Battles,Explosions/Remote violence,Violence against civilians",
    "has_fatalities": True,
    "sort": "significance",
    "limit": 10,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
events = r.json()["data"]

MCP Event monitor

json

{
  "tool": "gdelt_cloud_tool_call",
  "arguments": {
      "tool_name": "search_events",
      "tool_arguments": {
        "country": "Lebanon",
        "categories": ["Battles", "Explosions/Remote violence", "Violence against civilians"],
        "has_fatalities": true,
        "sort": "significance",
        "limit": 10
    }
  }
}

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"
}

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"]

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"]

MCP Story evidence

json

{
  "tool": "gdelt_cloud_tool_call",
  "arguments": {
    "tool_name": "search_stories",
    "tool_arguments": {
      "country": "Lebanon",
      "has_events": true,
      "has_fatalities": true,
      "sort": "significance",
      "limit": 5
    }
  }
}

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"
}

Step 5

Pivot to physical energy-infrastructure exposure

Move from narrative + events to a structural anchor: which energy assets are exposed in or near the affected area? The Energy Data category sources directly from Global Energy Monitor (GEM) and shares the country/region/continent expansion semantics with Events.

The agent now has a capacity-weighted energy mix for the country plus the specific operating assets within a proximity radius — feed both into a downstream brief or risk model.

REST Energy mix + proximity

python

# Energy mix in Lebanon (operating only)
mix = client.get("/api/v2/energy/assets/summary", params={
    "country": "Lebanon",
    "group_by": "tracker",
    "operating_only": True,
    "asset_class": "fixed",
}).json()

# Operating assets within 75 km of Beirut
near = client.get("/api/v2/energy/assets", params={
    "country": "Lebanon",
    "near": "33.85,35.66,75",
    "operating_only": True,
    "sort": "capacity_desc",
    "limit": 10,
}).json()

REST Energy mix + proximity

python

# Energy mix in Lebanon (operating only)
mix = client.get("/api/v2/energy/assets/summary", params={
    "country": "Lebanon",
    "group_by": "tracker",
    "operating_only": True,
    "asset_class": "fixed",
}).json()

# Operating assets within 75 km of Beirut
near = client.get("/api/v2/energy/assets", params={
    "country": "Lebanon",
    "near": "33.85,35.66,75",
    "operating_only": True,
    "sort": "capacity_desc",
    "limit": 10,
}).json()

MCP Energy summary + proximity

json

{
  "tool": "energy_tool_call",
  "arguments": {
    "tool_name": "energy_summarize_assets",
    "tool_arguments": {
      "country": "Lebanon",
      "group_by": "tracker",
      "operating_only": true,
      "asset_class": "fixed"
    }
  }
}

{
  "tool": "energy_tool_call",
  "arguments": {
    "tool_name": "energy_search_assets",
    "tool_arguments": {
      "country": "Lebanon",
      "near": "33.85,35.66,75",
      "operating_only": true,
      "sort": "capacity_desc",
      "limit": 10
    }
  }
}

Representative Energy proximity output

json

{
  "success": true,
  "data": [
    {
      "id": "oil_gas_plants:G100000123456",
      "gem_id": "G100000123456",
      "tracker": "oil_gas_plants",
      "tier": "main",
      "asset_class": "fixed",
      "name": "Zahrani Power Station",
      "status": "operating",
      "start_year": 2002,
      "retired_year": null,
      "fuel": "fossil liquids: fuel oil",
      "capacity": {
        "value": 469,
        "unit": "MW",
        "mw": 469,
        "mw_secondary": null
      },
      "geo": {
        "country": "Lebanon",
        "country_iso3": "LBN",
        "secondary_country_iso3": null,
        "region": "Asia",
        "subregion": "Western Asia",
        "continent": "Asia",
        "state_province": "South Governorate",
        "city": "Zahrani",
        "lat": 33.4858,
        "lon": 35.3306,
        "location_accuracy": "exact"
      },
      "owners_raw": "Électricité du Liban",
      "owners": [
        {
          "name": "Électricité du Liban",
          "entity_id": "E100001005678",
          "stake_pct": 100
        }
      ],
      "operators_raw": null,
      "operators": [],
      "parents_raw": "Government of Lebanon",
      "parents": [
        {
          "name": "Government of Lebanon",
          "entity_id": null,
          "stake_pct": null
        }
      ],
      "wiki_url": "https://www.gem.wiki/Zahrani_power_station",
      "detail_url": "/energy/oil_gas_plants/G100000123456",
      "api_url": "/api/v2/energy/assets/oil_gas_plants/G100000123456"
    },
    {
      "id": "solar:G100002071234",
      "gem_id": "G100002071234",
      "tracker": "solar",
      "tier": "utility",
      "asset_class": "fixed",
      "name": "Beirut Solar Phase 1",
      "status": "operating",
      "start_year": 2024,
      "retired_year": null,
      "fuel": "solar",
      "capacity": {
        "value": 24,
        "unit": "MW",
        "mw": 24,
        "mw_secondary": null
      },
      "geo": {
        "country": "Lebanon",
        "country_iso3": "LBN",
        "secondary_country_iso3": null,
        "region": "Asia",
        "subregion": "Western Asia",
        "continent": "Asia",
        "state_province": "Mount Lebanon",
        "city": null,
        "lat": 33.8541,
        "lon": 35.6612,
        "location_accuracy": "approximate"
      },
      "owners_raw": "Beirut Energy Holding",
      "owners": [
        {
          "name": "Beirut Energy Holding",
          "entity_id": null,
          "stake_pct": null
        }
      ],
      "operators_raw": null,
      "operators": [],
      "parents_raw": null,
      "parents": [],
      "wiki_url": "https://www.gem.wiki/Beirut_Solar_Phase_1",
      "detail_url": "/energy/solar/G100002071234",
      "api_url": "/api/v2/energy/assets/solar/G100002071234"
    }
  ],
  "pagination": {
    "limit": 10,
    "cursor": null,
    "next_cursor": null
  },
  "sort": "capacity_desc",
  "filters_echo": {
    "tracker": [],
    "country_iso3": [
      "LBN"
    ],
    "near": {
      "lat": 33.85,
      "lon": 35.66,
      "radiusKm": 75
    },
    "operating_only": true,
    "asset_class": "fixed"
  }
}

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

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

Story evidence

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.