Skip to main content
GET
/
api
/
v2
/
events
cURL
curl "https://gdeltcloud.com/api/v2/events" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
{
  "success": true,
  "data": [
    {
      "id": "conflict_13e29fd7",
      "url": "https://gdeltcloud.com/story/example-story",
      "primary_story_url": "https://gdeltcloud.com/story/example-story",
      "family": "conflict",
      "title": "Attack in Delft",
      "summary": "A conflict Event coded from linked source articles.",
      "event_date": "2026-04-15",
      "category": "Violence against civilians",
      "subcategory": "Attack",
      "domain": "CONFLICT",
      "event_code": "conflict_13e29fd7",
      "geo": {
        "country": "South Africa",
        "region": "Southern Africa",
        "continent": "Africa",
        "admin1": "Western Cape",
        "location": "Delft",
        "latitude": -33.955,
        "longitude": 18.634
      },
      "actors": [
        {
          "name": "Unknown armed actor",
          "country": null,
          "role": "actor1"
        }
      ],
      "metrics": {
        "significance": 0.3585,
        "goldstein_scale": -7,
        "magnitude": null,
        "systemic_importance": null,
        "propagation_potential": null,
        "market_sensitivity": null,
        "confidence": 0.82,
        "article_count": 1
      },
      "has_fatalities": true,
      "fatalities": 4,
      "story_refs": [
        {
          "id": "story_123",
          "url": "https://gdeltcloud.com/story/example-story",
          "title": "Delft mass shooting coverage",
          "story_date": "2026-04-15",
          "article_count": 1
        }
      ],
      "entity_refs": [],
      "top_articles": [
        {
          "url": "https://www.example.com/delft-mass-shooting",
          "title": "Delft mass shooting: child among 4 killed",
          "domain": "example.com",
          "rank": 1
        }
      ]
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
  },
  "sort": "significance"
}

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

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

​
event_family
enum<string>

Generated Event family.

Available options:
conflict,
cameoplus
​
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"

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

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

Example:

"attacks on energy infrastructure"

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

​
min_confidence
number

Event list/summary confidence threshold override, from 0 to 1. When supplied, it overrides the Event confidence threshold implied by confidence_profile; use confidence_profile=loose&min_confidence=0.9 for exhaustive Story matching with a custom Event confidence floor.

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

0.9

​
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

Event cards

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