Skip to main content
GET
/
api
/
v2
/
stories
/
summary
cURL
curl "https://gdeltcloud.com/api/v2/stories/summary" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
{
  "success": true,
  "group_by": "country",
  "data": [
    {
      "key": "Japan",
      "group_by": "country",
      "story_count": 8,
      "article_count": 44,
      "avg_article_count": 5.5,
      "max_article_count": 13,
      "stories_with_events": 6,
      "stories_with_fatalities": 0,
      "fatalities": 0,
      "avg_significance": 0.51,
      "max_significance": 0.83,
      "min_significance": 0.19,
      "linked_event_count": 11,
      "avg_linked_event_count": 1.38,
      "max_linked_event_count": 4,
      "avg_linked_event_significance": 0.47,
      "avg_linked_event_goldstein_scale": -1.9,
      "avg_linked_event_magnitude": 0.38,
      "avg_linked_event_systemic_importance": 0.33,
      "avg_linked_event_propagation_potential": 0.27,
      "avg_linked_event_market_sensitivity": 0.29,
      "avg_linked_event_confidence": 0.79,
      "avg_recency_score": 0.64,
      "metrics": {
        "significance": {
          "avg": 0.51,
          "max": 0.83,
          "min": 0.19
        },
        "article_count": {
          "total": 44,
          "avg": 5.5,
          "max": 13
        },
        "linked_events": {
          "count": 11,
          "avg_per_story": 1.38,
          "max_per_story": 4,
          "significance": {
            "avg": 0.47,
            "max": 0.78
          },
          "goldstein_scale": {
            "avg": -1.9,
            "max": 4.2,
            "avg_severity": 2.6
          },
          "cameoplus": {
            "magnitude": {
              "avg": 0.38,
              "max": 0.7
            },
            "systemic_importance": {
              "avg": 0.33,
              "max": 0.62
            },
            "propagation_potential": {
              "avg": 0.27,
              "max": 0.55
            },
            "market_sensitivity": {
              "avg": 0.29,
              "max": 0.61
            }
          },
          "confidence": {
            "avg": 0.79,
            "max": 0.94
          }
        },
        "recency_score": {
          "avg": 0.64
        },
        "fatalities": {
          "stories": 0,
          "rate": 0,
          "total": 0
        }
      },
      "metric_stats": {
        "significance": {
          "avg": 0.51,
          "max": 0.83,
          "min": 0.19
        }
      }
    }
  ]
}

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.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
group_by
enum<string>

Summary grouping dimension.

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

"date"

​
date_start
string<date>

Inclusive start date in YYYY-MM-DD. Alias start_date is accepted for compatibility.

Example:

"2026-04-11"

​
date_end
string<date>

Inclusive end date in YYYY-MM-DD. Alias end_date is accepted for compatibility.

Example:

"2026-04-17"

​
observed_start
string<date-time>

Optional ingestion/updated-at lower bound. Useful for live dashboards that need records observed today, even when event_date or cluster_date is earlier.

​
observed_end
string<date-time>

Optional ingestion/updated-at exclusive upper bound.

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

​
category
string

Stable product category, such as Protests, Riots, or a CAMEO+ domain such as POLITICAL or CRIME. Event endpoints accept a single value or comma-separated values.

Example:

"Protests"

​
event_category
string

Linked Event top-level category filter for Story endpoints. Use values such as Protests, Battles, or CAMEO+ domains like POLITICAL or CRIME. Accepts a single value or comma-separated values. This is distinct from Story cluster category.

​
subcategory
string

More specific Event subtype, CAMEO+ event description, or code group.

Example:

"Peaceful protest"

​
domain
enum<string>

CAMEO+ domain enum. Most useful with event_family=cameoplus.

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

For Stories, set true to require linked structured Events or false for Stories without linked Events.

Example:

true

​
has_fatalities
boolean

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

Example:

true

​
confidence_profile
enum<string>
default:precise

Quality profile for Event and Story list/summary endpoints. Default precise favors analyst-ready, non-duplicative results. strictest is highest precision; balanced is broader; loose is exhaustive/raw and disables the default quality filters. Detail endpoints remain exhaustive by ID.

Available options:
strictest,
precise,
balanced,
loose
Example:

"precise"

​
article_count_min
integer

Minimum Story article count.

Required range: x >= 0
Example:

2

​
article_count_max
integer

Maximum Story article count.

Required range: x >= 0
Example:

25

​
limit
integer
default:50

Number of summary buckets to return.

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

50

Response

200 - application/json

Story summary buckets

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