Monitor workflow · Corporate security / GSOC
Operations security routing
Route Mexico operating incidents, global critical violence, and Red Sea disruption as three questions with three response processes.
These are intentionally three Monitors: their geography, criteria, cadence, and response process differ. The public payload exposes email on/off and one Watch+ webhook URL; do not claim arbitrary email-recipient routing that is not in the API contract. A fatalities-only conflict Monitor is not a general criticality model. volume_spike is deferred; every trigger is new_matches.
POST /api/v2/monitors # specification 1 of 3
{
"name": "Mexico operations security",
"description": "Local security and operating disruption coverage for the Mexico response team.",
"subject": {
"type": "geography",
"countries": [
"MEX"
]
},
"criteria": {
"data": "events_and_stories",
"search": "security incident, civil unrest, transport disruption, facility access restriction",
"countries": [],
"family_filters": {
"cameoplus": {
"domains": [
"CRIME",
"INFRASTRUCTURE"
],
"subcategories": []
},
"conflict": {
"categories": [
"Protests",
"Riots",
"Violence against civilians"
],
"subcategories": []
},
"story": {
"categories": [
"conflict_security",
"cameoplus_infrastructure"
]
}
},
"fatalities_only": false,
"collapse_duplicates": true
},
"trigger": {
"type": "new_matches"
},
"schedule": {
"cadence": "hourly",
"timezone": "America/Mexico_City",
"daily_hour": 8
},
"delivery": {
"email": true
}
}
POST /api/v2/monitors # specification 2 of 3
{
"name": "Global fatal conflict events",
"description": "Fatal conflict Events across the operating-country list for global leadership.",
"subject": {
"type": "geography",
"countries": [
"MEX",
"GBR",
"DEU",
"JPN"
]
},
"criteria": {
"data": "events",
"countries": [],
"family_filters": {
"cameoplus": {
"domains": [],
"subcategories": []
},
"conflict": {
"categories": [
"Battles",
"Explosions/Remote violence",
"Violence against civilians"
],
"subcategories": []
}
},
"fatalities_only": true,
"collapse_duplicates": true
},
"trigger": {
"type": "new_matches"
},
"schedule": {
"cadence": "hourly",
"timezone": "UTC",
"daily_hour": 8
},
"delivery": {
"email": true
}
}
POST /api/v2/monitors # specification 3 of 3
{
"name": "Red Sea maritime disruption",
"description": "Shipping and port disruption near the southern Red Sea operating area.",
"subject": {
"type": "place",
"latitude": 15,
"longitude": 42,
"radius_km": 250
},
"criteria": {
"data": "events_and_stories",
"search": "port closure, vessel attack, shipping disruption, route diversion",
"countries": [],
"family_filters": {
"cameoplus": {
"domains": [
"ECONOMIC",
"INFRASTRUCTURE"
],
"subcategories": []
},
"conflict": {
"categories": [
"Explosions/Remote violence",
"Strategic developments"
],
"subcategories": []
},
"story": {
"categories": [
"cameoplus_infrastructure",
"conflict_security"
]
}
},
"fatalities_only": false,
"collapse_duplicates": true
},
"trigger": {
"type": "new_matches"
},
"schedule": {
"cadence": "hourly",
"timezone": "UTC",
"daily_hour": 8
},
"delivery": {
"email": true
}
}Expected notification result
Email summarizes the same run. Signed webhooks use this typed Constitution fixture; total, included, and truncation are explicit.
[
{
"name": "event",
"payload": {
"schema_version": "1",
"id": "evt_demo_event_001",
"type": "monitor.triggered",
"created_at": "2026-08-24T12:00:00.000Z",
"monitor": {
"id": "mon_demo_supply",
"name": "Supplier disruption watch"
},
"run": {
"id": "run_demo_event_001",
"scheduled_for": "2026-08-24T12:00:00.000Z",
"window_start": "2026-08-24T11:00:00.000Z",
"window_end": "2026-08-24T12:00:00.000Z",
"cadence": "hourly"
},
"trigger": {
"type": "new_matches",
"total_matches": 1,
"included_matches": 1,
"truncated": false,
"next_cursor": "eyJvIjowfQ"
},
"data": {
"matches": [
{
"kind": "event",
"family": "cameoplus",
"item": {
"id": "cameoplus:demo-event-001",
"url": "https://example.com/events/demo-event-001",
"primary_story_url": "https://example.com/news/demo-event-001",
"family": "cameoplus",
"title": "Port authority temporarily restricts cargo traffic",
"title_source": "coder_title",
"summary": "A temporary operating restriction affected cargo movements at the port.",
"event_date": "2026-08-24",
"observed_at": "2026-08-24T10:30:00.000Z",
"event_date_basis": "explicit_date",
"event_date_evidence": "The notice states the restriction began on August 24.",
"coded_at": "2026-08-24T11:00:00.000Z",
"updated_at": "2026-08-24T11:05:00.000Z",
"processed_at": "2026-08-24T11:05:00.000Z",
"category": "Economic activity",
"subcategory": "EC04",
"subcategory_label": "Trade Policy Action",
"taxonomy_status": "coded",
"domain": "ECONOMY",
"event_code": "EC04",
"geo": {
"country": "United States",
"region": "Northern America",
"continent": "North America",
"admin1": "California",
"location": "Los Angeles",
"latitude": 34.0522,
"longitude": -118.2437,
"geo_precision": 1,
"geo_precision_label": "city"
},
"geo_context": {
"location_country": "United States",
"actor_origin_countries": [
"United States"
]
},
"actors": [
{
"name": "Port authority",
"country": "United States",
"role": "source",
"primary": true
},
{
"name": "Cargo operators",
"country": null,
"role": "target",
"primary": true
}
],
"metrics": {
"significance": 0.62,
"severity_tier": "moderate",
"goldstein_scale": null,
"magnitude": 0.54,
"systemic_importance": 0.44,
"propagation_potential": 0.58,
"market_sensitivity": 0.61,
"confidence": 0.91,
"article_count": 4,
"evidence_source_count": 3,
"supporting_story_count": 1,
"metric_version": "v1"
},
"has_fatalities": null,
"fatalities": null,
"fatalities_basis": null,
"fatalities_corroboration": null,
"fatalities_evidence": null,
"fatalities_supporting_source_count": null,
"injured": null,
"civilians_killed": null,
"civilians_injured": null,
"civilian_targeting": null,
"civilian_targeting_label": null,
"story_refs": [
{
"id": "story-demo-001",
"url": "https://example.com/stories/story-demo-001",
"title": "Port traffic restricted",
"story_date": "2026-08-24",
"article_count": 4
}
],
"entity_refs": [
{
"id": "e_demo_port",
"name": "Port authority"
}
],
"top_articles": [
{
"url": "https://example.com/news/demo-event-001",
"title": "Port traffic restricted",
"domain": "example.com",
"domain_avatar_url": null,
"rank": 1
}
],
"language_breakdown": [
{
"language": "English",
"count": 4
}
],
"top_language": "English",
"search_score": null,
"incident": {
"uid": "cameoplus:demo-event-001",
"resolution": "unadjudicated",
"confidence": null
}
}
}
]
},
"links": {
"monitor": "https://gdeltcloud.com/monitors/mon_demo_supply",
"run": "https://gdeltcloud.com/monitors/mon_demo_supply/runs/run_demo_event_001",
"matches": "https://gdeltcloud.com/api/v2/monitors/mon_demo_supply/runs/run_demo_event_001/matches"
}
}
},
{
"name": "mixed",
"payload": {
"schema_version": "1",
"id": "evt_demo_mixed_001",
"type": "monitor.triggered",
"created_at": "2026-08-24T12:00:00.000Z",
"monitor": {
"id": "mon_demo_region",
"name": "Regional risk watch"
},
"run": {
"id": "run_demo_mixed_001",
"scheduled_for": "2026-08-24T12:00:00.000Z",
"window_start": "2026-08-24T11:00:00.000Z",
"window_end": "2026-08-24T12:00:00.000Z",
"cadence": "hourly"
},
"trigger": {
"type": "new_matches",
"total_matches": 2,
"included_matches": 2,
"truncated": false,
"next_cursor": "eyJvIjowfQ"
},
"data": {
"matches": [
{
"kind": "event",
"family": "cameoplus",
"item": {
"id": "cameoplus:demo-event-003",
"url": null,
"primary_story_url": null,
"family": "cameoplus",
"title": "Regulator opens a formal inquiry",
"title_source": "coder_title",
"summary": null,
"event_date": "2026-08-24",
"observed_at": null,
"event_date_basis": "publication_day_inference",
"event_date_evidence": null,
"coded_at": "2026-08-24T11:00:00.000Z",
"updated_at": "2026-08-24T11:00:00.000Z",
"processed_at": "2026-08-24T11:00:00.000Z",
"category": "Legal and regulatory",
"subcategory": "LR01",
"subcategory_label": "Regulatory Action",
"taxonomy_status": "coded",
"domain": "LEGAL",
"event_code": "LR01",
"geo": {
"country": "Singapore",
"region": "South-eastern Asia",
"continent": "Asia",
"admin1": null,
"location": "Singapore",
"latitude": 1.3521,
"longitude": 103.8198,
"geo_precision": 1,
"geo_precision_label": "city"
},
"geo_context": {
"location_country": "Singapore",
"actor_origin_countries": [
"Singapore"
]
},
"actors": [
{
"name": "Regulator",
"country": "Singapore",
"role": "source",
"primary": true
},
{
"name": "Operator",
"country": null,
"role": "target",
"primary": true
}
],
"metrics": {
"significance": 0.66,
"severity_tier": "moderate",
"goldstein_scale": null,
"magnitude": 0.5,
"systemic_importance": 0.59,
"propagation_potential": 0.46,
"market_sensitivity": 0.63,
"confidence": 0.9,
"article_count": 3,
"evidence_source_count": 2,
"supporting_story_count": 1
},
"has_fatalities": null,
"fatalities": null,
"fatalities_basis": null,
"fatalities_corroboration": null,
"fatalities_evidence": null,
"fatalities_supporting_source_count": null,
"injured": null,
"civilians_killed": null,
"civilians_injured": null,
"civilian_targeting": null,
"civilian_targeting_label": null,
"story_refs": [],
"entity_refs": [],
"top_articles": [],
"language_breakdown": [],
"top_language": null,
"search_score": null,
"incident": {
"uid": "cameoplus:demo-event-003",
"resolution": "unadjudicated",
"confidence": null
}
}
},
{
"kind": "story",
"item": {
"id": "story-demo-003",
"url": null,
"title": "Industry groups respond to inquiry",
"story_date": "2026-08-24",
"updated_at": "2026-08-24T11:10:00.000Z",
"processed_at": "2026-08-24T11:10:00.000Z",
"category": "Economy and business",
"category_code": "economy_business",
"subcategory": null,
"geo": {
"country": "Singapore",
"region": "South-eastern Asia",
"continent": "Asia",
"admin1": null,
"location": "Singapore",
"latitude": 1.3521,
"longitude": 103.8198,
"geo_precision": 1,
"geo_precision_label": "city"
},
"geo_provenance": null,
"geo_context": {
"location_country": "Singapore",
"actor_origin_countries": [
"Singapore"
]
},
"metrics": {
"significance": 0.51,
"article_count": 5,
"linked_event_count": 1,
"max_linked_event_significance": 0.66,
"civilian_targeting_event_count": 0
},
"has_events": true,
"has_fatalities": null,
"has_civilian_targeting": false,
"fatalities": null,
"linked_events": [
{
"id": "cameoplus:demo-event-003",
"title": "Regulator opens a formal inquiry"
}
],
"entity_refs": [],
"matched_categories": [
{
"code": "LEGAL",
"label": "Legal and regulatory"
}
],
"top_articles": [],
"language_breakdown": [],
"top_language": null,
"search_score": null
}
}
]
},
"links": {
"monitor": "https://gdeltcloud.com/monitors/mon_demo_region",
"run": "https://gdeltcloud.com/monitors/mon_demo_region/runs/run_demo_mixed_001",
"matches": "https://gdeltcloud.com/api/v2/monitors/mon_demo_region/runs/run_demo_mixed_001/matches"
}
}
},
{
"name": "truncated",
"payload": {
"schema_version": "1",
"id": "evt_demo_truncated_001",
"type": "monitor.triggered",
"created_at": "2026-08-24T12:00:00.000Z",
"monitor": {
"id": "mon_demo_high_volume",
"name": "High-volume country watch"
},
"run": {
"id": "run_demo_truncated_001",
"scheduled_for": "2026-08-24T12:00:00.000Z",
"window_start": "2026-08-24T11:00:00.000Z",
"window_end": "2026-08-24T12:00:00.000Z",
"cadence": "hourly"
},
"trigger": {
"type": "new_matches",
"total_matches": 37,
"included_matches": 1,
"truncated": true,
"next_cursor": "eyJvIjowfQ"
},
"data": {
"matches": [
{
"kind": "story",
"item": {
"id": "story-demo-truncated",
"url": null,
"title": "Representative result from a larger run",
"story_date": "2026-08-24",
"updated_at": null,
"processed_at": null,
"category": null,
"category_code": null,
"subcategory": null,
"geo": {
"country": "Brazil",
"region": "South America",
"continent": "South America",
"admin1": null,
"location": null,
"latitude": null,
"longitude": null,
"geo_precision": null,
"geo_precision_label": null
},
"geo_provenance": null,
"geo_context": {
"location_country": "Brazil",
"actor_origin_countries": []
},
"metrics": {
"significance": 0.42,
"article_count": 2,
"linked_event_count": 0,
"max_linked_event_significance": 0,
"civilian_targeting_event_count": 0
},
"has_events": false,
"has_fatalities": null,
"has_civilian_targeting": false,
"fatalities": null,
"linked_events": [],
"entity_refs": [],
"matched_categories": [],
"top_articles": [],
"language_breakdown": [],
"top_language": null,
"search_score": null
}
}
]
},
"links": {
"monitor": "https://gdeltcloud.com/monitors/mon_demo_high_volume",
"run": "https://gdeltcloud.com/monitors/mon_demo_high_volume/runs/run_demo_truncated_001",
"matches": "https://gdeltcloud.com/api/v2/monitors/mon_demo_high_volume/runs/run_demo_truncated_001/matches"
}
}
},
{
"name": "test",
"payload": {
"schema_version": "1",
"id": "evt_demo_test_001",
"type": "monitor.test",
"created_at": "2026-08-24T12:00:00.000Z",
"monitor": {
"id": "mon_demo_test",
"name": "Webhook setup test"
},
"run": null,
"trigger": null,
"data": {
"matches": []
},
"test": {
"status": "ok",
"message": "GDELT Cloud Monitor webhook test"
},
"links": {
"monitor": "https://gdeltcloud.com/monitors/mon_demo_test",
"run": null,
"matches": null
}
}
}
]The stored Monitor specifications
All three views use these same 3 public API objects.
[
{
"name": "Mexico operations security",
"description": "Local security and operating disruption coverage for the Mexico response team.",
"subject": {
"type": "geography",
"countries": [
"MEX"
]
},
"criteria": {
"data": "events_and_stories",
"search": "security incident, civil unrest, transport disruption, facility access restriction",
"countries": [],
"family_filters": {
"cameoplus": {
"domains": [
"CRIME",
"INFRASTRUCTURE"
],
"subcategories": []
},
"conflict": {
"categories": [
"Protests",
"Riots",
"Violence against civilians"
],
"subcategories": []
},
"story": {
"categories": [
"conflict_security",
"cameoplus_infrastructure"
]
}
},
"fatalities_only": false,
"collapse_duplicates": true
},
"trigger": {
"type": "new_matches"
},
"schedule": {
"cadence": "hourly",
"timezone": "America/Mexico_City",
"daily_hour": 8
},
"delivery": {
"email": true
}
},
{
"name": "Global fatal conflict events",
"description": "Fatal conflict Events across the operating-country list for global leadership.",
"subject": {
"type": "geography",
"countries": [
"MEX",
"GBR",
"DEU",
"JPN"
]
},
"criteria": {
"data": "events",
"countries": [],
"family_filters": {
"cameoplus": {
"domains": [],
"subcategories": []
},
"conflict": {
"categories": [
"Battles",
"Explosions/Remote violence",
"Violence against civilians"
],
"subcategories": []
}
},
"fatalities_only": true,
"collapse_duplicates": true
},
"trigger": {
"type": "new_matches"
},
"schedule": {
"cadence": "hourly",
"timezone": "UTC",
"daily_hour": 8
},
"delivery": {
"email": true
}
},
{
"name": "Red Sea maritime disruption",
"description": "Shipping and port disruption near the southern Red Sea operating area.",
"subject": {
"type": "place",
"latitude": 15,
"longitude": 42,
"radius_km": 250
},
"criteria": {
"data": "events_and_stories",
"search": "port closure, vessel attack, shipping disruption, route diversion",
"countries": [],
"family_filters": {
"cameoplus": {
"domains": [
"ECONOMIC",
"INFRASTRUCTURE"
],
"subcategories": []
},
"conflict": {
"categories": [
"Explosions/Remote violence",
"Strategic developments"
],
"subcategories": []
},
"story": {
"categories": [
"cameoplus_infrastructure",
"conflict_security"
]
}
},
"fatalities_only": false,
"collapse_duplicates": true
},
"trigger": {
"type": "new_matches"
},
"schedule": {
"cadence": "hourly",
"timezone": "UTC",
"daily_hour": 8
},
"delivery": {
"email": true
}
}
]After the notification
Scheduled checks cost 0 QU. Investigation and application calls use QU.
Triage canonical Event and Story cards from each webhook.
Execute the run replay_requests to retrieve the complete window.
Use historical summaries, facility radius, or maritime endpoints only in the owning team's workflow.