Skip to main content
GET
/
api
/
v2
/
stories
cURL
curl "https://gdeltcloud.com/api/v2/stories" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
{
  "success": true,
  "data": [
    {
      "id": "story_123",
      "url": "https://gdeltcloud.com/story/example-story",
      "title": "Data center projects in Asia",
      "story_date": "2026-04-15",
      "category": "infrastructure",
      "subcategory": null,
      "geo": {
        "country": "Japan",
        "region": "Eastern Asia",
        "continent": "Asia",
        "admin1": "Tokyo",
        "location": "Tokyo",
        "latitude": 35.6762,
        "longitude": 139.6503
      },
      "metrics": {
        "significance": 0.82,
        "article_count": 12,
        "linked_event_count": 2,
        "max_linked_event_significance": 0.71
      },
      "has_events": true,
      "has_fatalities": false,
      "fatalities": 0,
      "linked_events": [
        {
          "id": "cameoplus_abc123",
          "title": "Infrastructure investment announced"
        }
      ],
      "entity_refs": [],
      "top_articles": [
        {
          "url": "https://www.example.com/data-center",
          "title": "New data center project announced",
          "domain": "example.com",
          "rank": 1
        }
      ]
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
  },
  "sort": "significance"
}

Authorizations

​
Authorization
string
header
required

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

Query Parameters

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

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

​
story_category
string

Legacy Story-cluster category filter such as conflict_security or cameoplus_infrastructure. Prefer linked Event category/subcategory for product taxonomy filtering.

Example:

"conflict_security"

​
event_category
string

Deprecated alias for category on Story endpoints. Prefer category=Battles or a CAMEO+ domain such as category=CRIME.

​
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
​
search
string

Free-text semantic search. The API ranks the filtered candidate set by semantic similarity against stored Event or Story representations. It is not a lexical keyword filter and has no public similarity cutoff.

Example:

"attacks on energy infrastructure"

​
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

​
civilian_targeting
boolean

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

​
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

​
sort
enum<string>
default:significance

significance is the default analyst ranking. Use recent when freshness matters more than importance.

Available options:
significance,
recent
Example:

"significance"

​
limit
integer
default:25

Number of records to return.

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

25

​
cursor
string

Pagination cursor from pagination.next_cursor.

Response

200 - application/json

Story cards

​
success
enum<boolean>
Available options:
true
​
pagination
object
​
data
object[]
​
sort
enum<string>
default:significance
Available options:
significance,
recent