Search Events

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.

Geographic bounding box on event latitude/longitude, formatted as lat_min,lon_min,lat_max,lon_max. Use for sub-country precision (e.g. a strait or port area). Combine with country or use alone; lat must be in [-90,90] and lon in [-180,180].

Proximity filter around a point, formatted as lat,lon (two numbers). Combine with radius_km (default 100 km, capped at 2000). The point+radius is expanded to an enclosing bounding box, so it's a superset of the exact circle. Alternatively pass lat and lon separately — the shape an asset's geo.lat/geo.lon hands you. A malformed point returns 400 INVALID_NEAR; an explicit bbox takes precedence over near.

Latitude of the proximity point, in [-90,90]. Must be supplied together with lon (or use near=lat,lon instead). Pairs with radius_km.

Longitude of the proximity point, in [-180,180]. Must be supplied together with lat (or use near=lat,lon). Alias lng is accepted.

Radius in kilometres for the near / lat+lon proximity point. Defaults to 100 km and is capped at 2000 km so it stays a proximity filter rather than a hemisphere scan. Ignored when no point is given.

Deprecated legacy filter. Prefer category, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility.

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.

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.

Free-text semantic search. The API ranks the filtered candidate set by semantic similarity against stored Event or Story representations. It is not a lexical keyword filter and has no public similarity cutoff.

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.

Significance minimum filter. Composite 0-1 Event significance score.

Significance maximum filter. Composite 0-1 Event significance score.

Confidence minimum filter. Model confidence for the structured Event record.

Confidence maximum filter. Model confidence for the structured Event record.

Goldstein scale minimum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.

Goldstein scale maximum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.

Goldstein severity minimum filter. Absolute Goldstein intensity, regardless of positive or negative valence.

Goldstein severity maximum filter. Absolute Goldstein intensity, regardless of positive or negative valence.

Magnitude minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Magnitude maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Systemic importance minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Systemic importance maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Propagation potential minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Propagation potential maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Market sensitivity minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Market sensitivity maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.

Filter to items with at least one linked article in these source (origin) languages. Comma-separated ISO codes — en, zh, ar, es, fr, … — normalized case-insensitively and OR'd together; the alias language is accepted. Unknown codes are dropped rather than erroring.

Include best-effort representative article image URLs on each row — a top-level image_url plus top_articles[].image_url. Defaults to true; set false to skip image enrichment for a lighter, faster response.

significance is the default analyst ranking. Use recent when freshness matters more than importance.

Number of records to return.

Pagination cursor from pagination.next_cursor.