Skip to main content
POST
/
api
/
alerts
Create Alert
curl --request POST \
  --url https://gdeltcloud.com/api/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "Middle East Conflicts Monitor",
  "natural_language_description": "Monitor violent conflicts and protests in Middle Eastern countries",
  "sql_query": "SELECT day, actor1_name, actor2_name, event_code, goldstein_scale, action_geo_country_code FROM gdelt_events WHERE {TIME_FILTER} AND action_geo_country_code IN ('SY', 'IQ', 'IR', 'YE') AND event_root_code IN ('18', '19', '20') ORDER BY goldstein_scale ASC LIMIT 50",
  "tables_used": [
    "<string>"
  ],
  "check_frequency": "12hourly"
}
EOF
{
  "success": true,
  "alert": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "sql_query": "<string>",
    "tables_used": [
      "<string>"
    ],
    "check_frequency": "hourly",
    "notification_email": "[email protected]",
    "enabled": true,
    "created_at": "<string>",
    "updated_at": "<string>",
    "description": "<string>",
    "natural_language_description": "<string>",
    "last_triggered_at": "<string>",
    "last_check_at": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
default:Middle East Conflicts Monitor
required

Alert name (1-100 characters)

Required string length: 1 - 100
​
natural_language_description
string
default:Monitor violent conflicts and protests in Middle Eastern countries
required

Natural language description of what to monitor

​
sql_query
string
default:SELECT day, actor1_name, actor2_name, event_code, goldstein_scale, action_geo_country_code FROM gdelt_events WHERE {TIME_FILTER} AND action_geo_country_code IN ('SY', 'IQ', 'IR', 'YE') AND event_root_code IN ('18', '19', '20') ORDER BY goldstein_scale ASC LIMIT 50
required

SQL query with {TIME_FILTER} placeholder

​
tables_used
string[]
required

GDELT tables used (e.g., ['events'])

Minimum array length: 1
​
check_frequency
enum<string>
default:12hourly
required

Alert frequency

Available options:
hourly,
12hourly,
daily,
weekly
​
description
string | null
default:Monitors high-intensity conflict events in Middle Eastern countries

Optional alert description

Response

Successful response

​
success
boolean
required
​
alert
object
required