Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Principle

Anchor analysis in GDELT Cloud generated data. The structured Events database is the backbone of the product: start from Events or Event summaries whenever the user asks what happened, where, how often, who was involved, whether risk is rising, or how a pattern is changing.
  • Events first for structured incidents, actors, geo, categories, fatalities, Goldstein scale, and CAMEO+ metrics.
  • Stories second for clustered narratives and article evidence.
  • Summaries for dashboards and trends.
  • Entities for linked people and organizations.
Use macro-finance, prediction-market, and web-research tools as enrichment, verification, and color.

​
REST Pattern

Event and Story list/summary endpoints default to confidence_profile=precise for clean, analyst-ready results. Add confidence_profile=loose only when exhaustive/raw retrieval is required. 
# Scan Events
GET /api/v2/events/summary?country=India&category=Protests&group_by=date&date_start=2026-03-18&date_end=2026-04-17

# Drill into Events
GET /api/v2/events?country=India&category=Protests&date_start=2026-04-11&date_end=2026-04-17&sort=significance

# Search Stories
GET /api/v2/stories?continent=Asia&search=new%20data%20center%20projects&article_count_min=1&sort=significance

# Paginate source articles
GET /api/v2/stories/{story_id}/articles?limit=25

​
MCP Pattern

  1. gdelt_cloud_tool_list
  2. gdelt_cloud_tool_get
  3. gdelt_cloud_tool_call
  4. Enrich with macro_finance_*, prediction_market_*, and web_research_* when relevant.

​
Geography

Use plain English country names. ISO-3 and legacy FIPS aliases are accepted, but documented input and output should use names. For Events, country, region, and continent match broadly across location and actor-origin geography. For Stories, those filters match linked Event primary location only. admin1 filters location only and must be discovered by country through /api/v2/geo/admin1 or list_admin1.

​
Recommended Defaults

NeedDefault
Monitoringsort=significance
Freshest itemssort=recent
Evidence previewuse inline top_articles
Full evidenceuse /api/v2/stories/{story_id}/articles
Dashboardsuse summary endpoints first
Geouse country/region/continent names
Qualitykeep confidence_profile=precise; use loose for exhaustive/raw retrieval

​
Output

For quick questions, answer directly. For deeper work, use: 
## Bottom Line
## Structured Event Evidence
## Story / Article Evidence
## Entity Links
## External Context
## Watch Next