Skip to main content
GET
/
api
/
v1
/
conflict-events
List Conflict Events
curl --request GET \
  --url https://gdeltcloud.com/api/v1/conflict-events \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "events": [
    {
      "id": "<string>",
      "cluster_id": "<string>",
      "event_date": "2023-12-25",
      "disorder_type": "<string>",
      "event_type": "<string>",
      "sub_event_type": "<string>",
      "actor1": "<string>",
      "actor2": "<string>",
      "interaction": "<string>",
      "civilian_targeting": true,
      "country": "<string>",
      "admin1": "<string>",
      "location": "<string>",
      "latitude": 123,
      "longitude": 123,
      "fatalities": 123,
      "notes": "<string>",
      "tags": [
        "<string>"
      ],
      "confidence": 123,
      "source_urls": [
        "<string>"
      ]
    }
  ],
  "metadata": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "execution_time_ms": 123
  }
}

Authorizations

​
Authorization
string
header
required

API key format: gdelt_sk_<64-hex-chars>. Generate in Dashboard → Settings → API Keys.

Query Parameters

​
days
integer
default:1

Lookback window in days from date. Default 1 = today only.

Required range: 1 <= x <= 30
​
date
string<date>

Anchor/end date (YYYY-MM-DD). Defaults to today UTC.

Example:

"2026-07-03"

​
limit
integer
default:20

Number of events to return (max 100). Default 20.

Required range: 1 <= x <= 100
​
offset
integer
default:0

Pagination offset.

Required range: x >= 0
​
country
string

Full English country name where the event occurred (e.g. 'Ukraine', 'Sudan', 'Israel', 'Gaza Strip').

Example:

"Ukraine"

​
admin1
string

State/province name. Use with country. Examples: 'Donetsk Oblast', 'Khartoum', 'Aleppo'.

Example:

"Donetsk Oblast"

​
disorder_type
enum<string>

Top-level ACLED disorder classification.

Available options:
Political violence,
Demonstrations,
Strategic developments
​
event_type
enum<string>

ACLED event type.

Available options:
Battles,
Protests,
Riots,
Explosions/Remote violence,
Violence against civilians,
Strategic developments
​
sub_event_type
enum<string>

ACLED sub-event type — most specific classification level.

Available options:
Government regains territory,
Non-state actor overtakes territory,
Armed clash,
Excessive force against protesters,
Protest with intervention,
Peaceful protest,
Violent demonstration,
Mob violence,
Chemical weapon,
Air/drone strike,
Suicide bomb,
Shelling/artillery/missile attack,
Remote explosive/landmine/IED,
Grenade,
Sexual violence,
Attack,
Abduction/forced disappearance,
Agreement,
Arrests,
Change to group/activity,
Disrupted weapons use,
Headquarters or base established,
Looting/property destruction,
Non-violent transfer of territory,
Other
​
interaction
enum<string>

ACLED normalized actor-pair label encoding who did what to whom. Format: 'ActorType1–ActorType2' (lower-numbered type first), or 'ActorType only' for one-sided events.

Available options:
State forces only,
State forces–State forces,
State forces–Rebel groups,
State forces–Political militias,
State forces–Identity militias,
State forces–Rioters,
State forces–Protesters,
State forces–Civilians,
State forces–External/Other forces,
Rebel groups only,
Rebel groups–Rebel groups,
Rebel groups–Political militias,
Rebel groups–Identity militias,
Rebel groups–Rioters,
Rebel groups–Protesters,
Rebel groups–Civilians,
Rebel groups–External/Other forces,
Political militias only,
Political militias–Political militias,
Political militias–Identity militias,
Political militias–Rioters,
Political militias–Protesters,
Political militias–Civilians,
Political militias–External/Other forces,
Identity militias only,
Identity militias–Identity militias,
Identity militias–Rioters,
Identity militias–Protesters,
Identity militias–Civilians,
Identity militias–External/Other forces,
Rioters only,
Rioters–Rioters,
Rioters–Protesters,
Rioters–Civilians,
Rioters–External/Other forces,
Protesters only,
Protesters–Protesters,
Protesters–Civilians,
Protesters–External/Other forces,
Civilians only,
Civilians–Civilians,
External/Other forces–Civilians,
External/Other forces only,
External/Other forces–External/Other forces
​
civilian_targeting
boolean

If true, only return events where civilians were the primary target.

​
fatalities
boolean

If true, only return events with reported fatalities > 0.

​
search
string

Natural-language semantic search query. When provided, results are ranked by embedding cosine similarity (text-embedding-3-small, 1536 dims) instead of chronological order. The query is embedded server-side and matched against pre-computed event note embeddings. Only events with a stored embedding (all non-sentinel events) are returned. Fully combinable with all other filters (country, event_type, disorder_type, date, etc.). Examples: 'airstrikes on civilian infrastructure', 'protest crackdown', 'rebel advance territorial control', 'military offensive artillery shelling'.

Example:

"airstrikes civilians residential areas"

Response

Success

​
success
boolean
​
events
object[]
​
metadata
object