Summarize Events
Return dashboard-ready Event rollups by date, geography, category, or subcategory. Use group_by=subcategory under a parent category such as Battles to discover scoped sub-event buckets like Government regains territory, then reuse category+subcategory on /api/v2/events to fetch instances. Summaries use the same broad result coverage as Event lists and are designed for discovery before drilling into Events.
Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Summary grouping dimension. For Events, category is Conflict event type or CAMEO+ domain and subcategory is Conflict sub-event type or CAMEO+ event description/code. For Stories, category/subcategory grouping uses linked Event taxonomy; use story_category only as a Story-cluster filter.
date, country, region, continent, category, subcategory "date"
Inclusive start date in YYYY-MM-DD, matched against the event or story date. Alias start_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
"2026-04-11"
Inclusive end date in YYYY-MM-DD, matched against the event or story date. Alias end_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
"2026-04-17"
Country filter, resolved through the shared resolveCountryInput layer so a plain English country name (United States), an ISO-2 code (US), an ISO-3 code (USA), or a common alias (UK, UAE, Czechia) all work interchangeably; output normalizes to the country name. Accepts a comma-separated list (any part unresolvable → 400 INVALID_COUNTRY), and can be combined with region/continent.
"Lebanon"
Plain English region such as Middle East, Western Africa, South Asia, or Europe. The backend expands this value to an ISO-3 country list; Events match location and actor-origin countries, while Stories match linked Event primary location.
Africa, Asia, Middle East, Northern Africa, Western Africa, Eastern Africa, Middle Africa, Southern Africa, Europe, Eastern Europe, South Asia, Southeast Asia, East Asia, Central Asia, North America, Central America, Caribbean, South America, Oceania "Middle East"
Plain English continent such as Africa, Asia, Europe, North America, South America, or Oceania. The backend expands this value to an ISO-3 country list; Events match location and actor-origin countries, while Stories match linked Event primary location.
Africa, Asia, Europe, North America, South America, Oceania "Africa"
Optional state/province/admin1 location filter. Discover valid values through /api/v2/geo/admin1. Filters Event or Story location only, not actor origin.
"Beirut"
Geographic bounding box on event latitude/longitude, formatted as lat_min,lon_min,lat_max,lon_max. Use for sub-country precision (e.g. a strait or port area). Combine with country or use alone; lat must be in [-90,90] and lon in [-180,180].
^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$"11.5,42.5,13.5,44.5"
Deprecated legacy filter. Prefer category, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility.
conflict, cameoplus Stable linked Event product category. Use a Conflict event type such as Battles, Protests, or Explosions/Remote violence, or one CAMEO+ domain such as POLITICAL, INFRASTRUCTURE, or CRIME; values may be single or comma-separated. On Story endpoints this filters linked Event evidence. Use story_category only for legacy Story-cluster categories such as conflict_security. Full list: Taxonomy & Codes.
"Battles"
More specific linked Event subtype, CAMEO+ event description, or CAMEO+ code. Requires parent category and must belong to at least one selected category. For Conflict categories, use sub-event types such as Armed clash, Peaceful protest, or Air/drone strike. Validation errors include accepted_values, nearest_values when practical, and a corrected example. Full list: Taxonomy & Codes.
"Armed clash"
Deprecated legacy CAMEO+ domain enum. Prefer category/categories for new integrations; retained for backwards compatibility. Full list: Taxonomy & Codes.
POLITICAL, ECONOMIC, CORPORATE, TECHNOLOGY, INFRASTRUCTURE, HEALTH, DEMOGRAPHIC, INFORMATION, ENVIRONMENT, CRIME Set true for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.
true
Filter Conflict-linked evidence by ACLED civilian_targeting. true keeps records where civilians are the primary target; false excludes those records.
Significance minimum filter. Composite 0-1 Event significance score.
0 <= x <= 1Significance maximum filter. Composite 0-1 Event significance score.
0 <= x <= 1Confidence minimum filter. Model confidence for the structured Event record.
0 <= x <= 1Confidence maximum filter. Model confidence for the structured Event record.
0 <= x <= 1Goldstein scale minimum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.
-10 <= x <= 10Goldstein scale maximum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.
-10 <= x <= 10Goldstein severity minimum filter. Absolute Goldstein intensity, regardless of positive or negative valence.
0 <= x <= 10Goldstein severity maximum filter. Absolute Goldstein intensity, regardless of positive or negative valence.
0 <= x <= 10Magnitude minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 10Magnitude maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 10Systemic importance minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 1Systemic importance maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 1Propagation potential minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 1Propagation potential maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 1Market sensitivity minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 1Market sensitivity maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
0 <= x <= 1Filter to Events with at least one linked article in these source (origin) languages. Comma-separated ISO codes (en, zh, ar, …), OR'd; alias language accepted. Caveat: honored for every non-date group_by, and for a group_by=date query that also carries another qualifying filter — but IGNORED (and reported under applied_filters.ignored) on the lightweight group_by=date fast path with no other filter.
"en,zh"
Number of summary buckets to return.
1 <= x <= 50050