Skip to main content

​
Overview

The Alerts system allows you to create custom monitoring rules that automatically check for matching GDELT events and send email notifications when matches are found. Set up alerts to track protests, conflicts, diplomatic events, or any other global activity.

Real-time Monitoring

Alerts run on your chosen schedule (hourly, daily, or weekly)

Email Notifications

Receive detailed emails when new matching events are detected

Custom SQL Queries

Use AI-generated or custom SQL for precise event filtering

Historical Results

Access all past alert results from your dashboard

​
Creating an Alert

Alerts are created using the GDELT Agent interface or via the API. Use the GDELT Agent to describe what you want to monitor in plain English.
1

Navigate to Alerts

Go to Alerts in the sidebar and click Create New Alert
2

Describe your alert

Tell the AI what you want to monitor:
Alert me when there are protests in France with more than 500 mentions
3

Review generated SQL

The AI will generate SQL query with explanations:
SELECT 
  day,
  actor1_name,
  actor2_name,
  event_code,
  goldstein_scale,
  num_mentions,
  source_url
FROM gdelt_events
WHERE {TIME_FILTER}
  AND event_root_code = '14'  -- Protests
  AND action_geo_country_code = 'FRA'
  AND num_mentions > 500
ORDER BY num_mentions DESC
LIMIT 100
The {TIME_FILTER} placeholder is automatically replaced based on your alert frequency.
4

Configure alert settings

Set alert parameters:
  • Name: Descriptive alert name
  • Frequency: How often to check (hourly, 12-hourly, daily, weekly)
  • Email: Where to send notifications
  • Description: Optional notes about the alert
5

Activate alert

Click Create Alert to activate monitoring
Your alert is now active and will run on the specified schedule.

​
Method 2: Direct SQL

For advanced users, create alerts with custom SQL queries.
1

Open SQL mode

Click Advanced → Custom SQL when creating an alert
2

Write your query

Include the {TIME_FILTER} placeholder in your WHERE clause:
SELECT 
  day,
  actor1_name,
  actor2_name,
  event_code,
  goldstein_scale,
  ROUND(avg_tone, 2) as sentiment
FROM gdelt_events
WHERE {TIME_FILTER}
  AND actor1_country_code = 'USA'
  AND actor2_country_code = 'CHN'
  AND quad_class IN (3, 4)  -- Material cooperation/conflict
ORDER BY goldstein_scale
LIMIT 50
Always include {TIME_FILTER} in your WHERE clause. This placeholder is required for time-based filtering.
3

Test the query

Click Test Query to preview results before creating the alert
4

Configure and save

Set frequency, email, and name, then save the alert

​
Alert Frequencies

Choose how often your alert should check for new events:
FrequencyCheck IntervalBest ForExample Use Case
HourlyEvery hourBreaking news, urgent monitoringMarket-moving events, security threats
12-HourlyTwice per dayRegular updatesDaily briefings, routine monitoring
DailyOnce per dayGeneral trackingWeekly reports, trend analysis
WeeklyOnce per weekLong-term trendsMonthly summaries, research projects
Start with daily alerts and adjust frequency based on result volume and urgency needs.

​
Understanding

The {TIME_FILTER} placeholder is automatically replaced with appropriate date filtering based on your alert frequency: 
day >= today() - 1 AND dateTime >= now() - INTERVAL 1 HOUR
Checks events from the last hour
Never hardcode dates in alert queries. Always use {TIME_FILTER} to ensure proper time-based filtering.

​
Email Notifications

​
Notification Content

Alert emails include:
  • Alert name and description
  • Number of matching events found
  • Summary of top results
  • Link to view full results in dashboard
  • Direct action links (view, modify, or disable alert)

​
Notification Settings

Update the email address in Alert Settings → Edit → Notification Email
Toggle Enabled to false to stop notifications while keeping the alert
Permanently delete an alert from the Alerts page using the trash icon

​
Managing Alerts

​
View Alert Results

Access historical alert results from your dashboard:
1

Navigate to Alerts

Click Alerts in the sidebar to see all your alerts
2

View alert history

Click on any alert to see:
  • Recent trigger history
  • Result counts over time
  • Full result data for each trigger
3

Export data

Download results as CSV or JSON for further analysis

​
Modify Alerts

1

Select alert

Find the alert you want to modify in your alerts list
2

Edit settings

Click Edit to modify:
  • Alert name or description
  • SQL query (be careful with this!)
  • Check frequency
  • Notification email
  • Enabled status
3

Test changes

Click Test Query to verify your modifications work correctly
4

Save

Click Save Changes to apply updates
Changes take effect on the next scheduled check.

​
Disable vs Delete

ActionEffectRecoverableUse When
DisableStops checks and notifications, keeps historyYesTemporary pause
DeletePermanently removes alert and historyNoNo longer needed
Use Disable for temporary pauses. Only Delete when you’re certain you won’t need the alert again.

​
Example Alert Patterns

​
Conflict Monitoring

SELECT 
  day,
  actor1_name,
  actor2_name,
  event_code,
  goldstein_scale,
  num_mentions
FROM gdelt_events
WHERE {TIME_FILTER}
  AND event_root_code = '19'  -- Use military force
  AND action_geo_country_code IN ('IRQ', 'SYR', 'AFG')
  AND num_mentions > 100
ORDER BY goldstein_scale
LIMIT 50

​
Political Events

SELECT 
  day,
  actor1_name,
  actor2_name,
  event_code,
  goldstein_scale,
  source_url
FROM gdelt_events
WHERE {TIME_FILTER}
  AND event_base_code = '030'  -- Consult
  AND actor1_type1_code = 'GOV'
  AND actor2_type1_code = 'GOV'
  AND (actor1_country_code != actor2_country_code)
ORDER BY goldstein_scale DESC
LIMIT 50

​
Theme Tracking

SELECT 
  date,
  source_common_name,
  document_identifier,
  v2_themes,
  v1_5_tone
FROM gdelt_gkg
WHERE {TIME_FILTER}
  AND (v1_themes LIKE '%ENV_CLIMATECHANGE%' 
       OR v2_themes LIKE '%ENV_CLIMATECHANGE%')
ORDER BY date DESC
LIMIT 100