Skip to main content
GET
/
api
/
v2
/
events
/
summary
cURL
curl "https://gdeltcloud.com/api/v2/events/summary" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
{
  "success": true,
  "group_by": "date",
  "data": [
    {
      "key": "2026-04-15",
      "group_by": "date",
      "event_count": 12,
      "conflict_event_count": 7,
      "cameoplus_event_count": 5,
      "fatality_event_count": 2,
      "fatality_event_rate": 0.167,
      "fatalities": 6,
      "article_count": 38,
      "avg_article_count": 3.17,
      "max_article_count": 9,
      "avg_significance": 0.42,
      "max_significance": 0.86,
      "min_significance": 0.12,
      "avg_goldstein_scale": -3.8,
      "min_goldstein_scale": -9.5,
      "max_goldstein_scale": 3.4,
      "avg_goldstein_severity": 4.1,
      "avg_magnitude": 0.44,
      "avg_systemic_importance": 0.36,
      "avg_propagation_potential": 0.31,
      "avg_market_sensitivity": 0.18,
      "avg_confidence": 0.74,
      "metrics": {
        "significance": {
          "avg": 0.42,
          "max": 0.86,
          "min": 0.12
        },
        "goldstein_scale": {
          "avg": -3.8,
          "min": -9.5,
          "max": 3.4,
          "avg_severity": 4.1
        },
        "cameoplus": {
          "magnitude": {
            "avg": 0.44,
            "max": 0.72
          },
          "systemic_importance": {
            "avg": 0.36,
            "max": 0.68
          },
          "propagation_potential": {
            "avg": 0.31,
            "max": 0.59
          },
          "market_sensitivity": {
            "avg": 0.18,
            "max": 0.41
          }
        },
        "confidence": {
          "avg": 0.74,
          "max": 0.91
        },
        "article_count": {
          "total": 38,
          "avg": 3.17,
          "max": 9
        },
        "fatalities": {
          "events": 2,
          "rate": 0.167,
          "total": 6
        }
      },
      "metric_stats": {
        "significance": {
          "avg": 0.42,
          "max": 0.86,
          "min": 0.12
        }
      }
    }
  ]
}

Authorizations

​
Authorization
string
header
required

GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....

Query Parameters

​
group_by
enum<string>

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.

Available options:
date,
country,
region,
continent,
category,
subcategory
Example:

"date"

​
date_start
string<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.

Example:

"2026-04-11"

​
date_end
string<date>

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.

Example:

"2026-04-17"

​
country
string

Documented input is a plain English country name. ISO-3 and legacy FIPS aliases are accepted; output normalizes to the country name.

Example:

"Lebanon"

​
region
string

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.

Example:

"Middle East"

​
continent
string

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.

Example:

"Africa"

​
admin1
string

Optional state/province/admin1 location filter. Discover valid values through /api/v2/geo/admin1. Filters Event or Story location only, not actor origin.

Example:

"Beirut"

​
bbox
string

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

Pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$
Example:

"11.5,42.5,13.5,44.5"

​
event_family
enum<string>

Deprecated legacy filter. Prefer category, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility.

Available options:
conflict,
cameoplus
​
category
string

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.

Example:

"Battles"

​
subcategory
string

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.

Example:

"Armed clash"

​
domain
enum<string>

Deprecated legacy CAMEO+ domain enum. Prefer category/categories for new integrations; retained for backwards compatibility.

Available options:
POLITICAL,
ECONOMIC,
CORPORATE,
TECHNOLOGY,
INFRASTRUCTURE,
HEALTH,
DEMOGRAPHIC,
INFORMATION,
ENVIRONMENT,
CRIME
​
has_fatalities
boolean

Set true for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.

Example:

true

​
civilian_targeting
boolean

Filter Conflict-linked evidence by ACLED civilian_targeting. true keeps records where civilians are the primary target; false excludes those records.

​
significance_min
number

Significance minimum filter. Composite 0-1 Event significance score.

Required range: 0 <= x <= 1
​
significance_max
number

Significance maximum filter. Composite 0-1 Event significance score.

Required range: 0 <= x <= 1
​
confidence_min
number

Confidence minimum filter. Model confidence for the structured Event record.

Required range: 0 <= x <= 1
​
confidence_max
number

Confidence maximum filter. Model confidence for the structured Event record.

Required range: 0 <= x <= 1
​
goldstein_scale_min
number

Goldstein scale minimum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.

Required range: -10 <= x <= 10
​
goldstein_scale_max
number

Goldstein scale maximum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.

Required range: -10 <= x <= 10
​
goldstein_severity_min
number

Goldstein severity minimum filter. Absolute Goldstein intensity, regardless of positive or negative valence.

Required range: 0 <= x <= 10
​
goldstein_severity_max
number

Goldstein severity maximum filter. Absolute Goldstein intensity, regardless of positive or negative valence.

Required range: 0 <= x <= 10
​
magnitude_min
number

Magnitude minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 10
​
magnitude_max
number

Magnitude maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 10
​
systemic_importance_min
number

Systemic importance minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 1
​
systemic_importance_max
number

Systemic importance maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 1
​
propagation_potential_min
number

Propagation potential minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 1
​
propagation_potential_max
number

Propagation potential maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 1
​
market_sensitivity_min
number

Market sensitivity minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 1
​
market_sensitivity_max
number

Market sensitivity maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Required range: 0 <= x <= 1
​
limit
integer
default:50

Number of summary buckets to return.

Required range: 1 <= x <= 500
Example:

50

Response

200 - application/json

Event summary buckets

​
success
enum<boolean>
Available options:
true
​
data
object[]