v1
latestOpenAPI 3.0.32026-07-226744340.8 KBSummarize Stories
Return dashboard-ready Story rollups by date, geography, category, or subcategory. Summaries use broad result coverage and linked-Event aggregation. Use category/subcategory to filter by linked Event taxonomy. For group_by=category or group_by=subcategory, buckets are linked-Event taxonomy buckets, so narrative-only Stories are not counted in those taxonomy buckets.
Query parameters
Summary grouping dimension. For Events, category is Conflict event type or CAMEO+ domain and subcategory is Conflict sub-event type or CAMEO+ event description/code. For Stories, category/subcategory grouping uses linked Event taxonomy; use story_category only as a Story-cluster filter.
Inclusive start date in YYYY-MM-DD, matched against the event or story date. Alias start_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
Inclusive end date in YYYY-MM-DD, matched against the event or story date. Alias end_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
Country filter, resolved through the shared resolveCountryInput layer so a plain English country name (United States), an ISO-2 code (US), an ISO-3 code (USA), or a common alias (UK, UAE, Czechia) all work interchangeably; output normalizes to the country name. Accepts a comma-separated list (any part unresolvable → 400 INVALID_COUNTRY), and can be combined with region/continent.
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.
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.
Optional state/province/admin1 location filter. Discover valid values through /api/v2/geo/admin1. Filters Event or Story location only, not actor origin.
Bounding box lat_min,lon_min,lat_max,lon_max. Keeps stories with AT LEAST ONE linked event inside the box — the same linked-event geography semantics as country/admin1. Note the returned linked_event_count / fatalities stay FULL-story aggregates, not box-restricted. Malformed or out-of-range values return 400 INVALID_BBOX.
Stable linked Event product category. Use a Conflict event type such as Battles, Protests, or Explosions/Remote violence, or one CAMEO+ domain such as POLITICAL, INFRASTRUCTURE, or CRIME; values may be single or comma-separated. On Story endpoints this filters linked Event evidence. Use story_category only for legacy Story-cluster categories such as conflict_security. Full list: Taxonomy & Codes.
Legacy Story-cluster category filter such as conflict_security or cameoplus_infrastructure. Prefer linked Event category/subcategory for product taxonomy filtering.
Deprecated alias for category on Story endpoints. Prefer category=Battles or a CAMEO+ domain such as category=CRIME. Full list: Taxonomy & Codes.
More specific linked Event subtype, CAMEO+ event description, or CAMEO+ code. Requires parent category and must belong to at least one selected category. For Conflict categories, use sub-event types such as Armed clash, Peaceful protest, or Air/drone strike. Validation errors include accepted_values, nearest_values when practical, and a corrected example. Full list: Taxonomy & Codes.
Deprecated legacy CAMEO+ domain enum. Prefer category/categories for new integrations; retained for backwards compatibility. Full list: Taxonomy & Codes.
For Stories, set true to require linked structured Events or false for Stories without linked Events.
Set true for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.
Filter Conflict-linked evidence by ACLED civilian_targeting. true keeps records where civilians are the primary target; false excludes those records.
Minimum Story article count.
Maximum Story article count.
Filter to Stories with at least one linked article in these source (origin) languages. Comma-separated ISO codes (en, zh, ar, …), OR'd; alias language accepted. Caveat: honored for every non-date group_by, and for a group_by=date query that also carries another qualifying filter — but IGNORED (and reported under applied_filters.ignored) on the lightweight group_by=date fast path with no other filter.
Number of summary buckets to return.
Response
Story summary buckets
Example response
{
"data": [
{
"metrics": {
"significance": {
"avg": 0.5,
"max": 0.88,
"min": 0.12
},
"article_count": {
"total": 25,
"avg": 5,
"min": 2,
"max": 11
},
"linked_events": {
"count": {
"total": 7,
"avg": 1.4,
"min": 0,
"max": 3,
"stories_with_events": 4,
"story_only_count": 1
},
"significance": {
"avg": 0.62,
"min": 0.18,
"max": 0.94
},
"goldstein_scale": {
"avg": -3.2,
"min": -7.5,
"max": 1.5,
"avg_severity": 3.8
},
"goldstein_severity": {
"avg": 3.8,
"min": 0.8,
"max": 7.5
},
"magnitude": {
"avg": 5.5,
"min": 1.1,
"max": 8.4
},
"systemic_importance": {
"avg": 0.44,
"min": 0.12,
"max": 0.77
},
"propagation_potential": {
"avg": 0.41,
"min": 0.09,
"max": 0.72
},
"market_sensitivity": {
"avg": 0.39,
"min": 0.04,
"max": 0.68
},
"confidence": {
"avg": 0.81,
"min": 0.51,
"max": 0.96
}
},
"recency_score": {
"avg": 1
},
"fatalities": {
"stories": 1,
"rate": 0.2,
"total": 2
}
}
}
]
}