Skip to main content
GET
/
v1
/
events
List Events
curl --request GET \
  --url https://api.example.com/v1/events
Returns a paginated list of events. Categorical filters accept multiple values by repeating the parameter.

​
Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number, starting at 1 (default: 1)
page_sizeintegerNoResults per page, 1–500 (default: 50)
event_categorystring[]NoFilter by event category (repeatable)
event_typestring[]NoFilter by event type within category (repeatable)
event_subtypestring[]NoFilter by event subtype (repeatable)
countrystring[]NoFilter by country code (repeatable)
date_fromstringNoInclusive start date (YYYY-MM-DD)
date_tostringNoInclusive end date (YYYY-MM-DD)
searchstringNoFull-text search across title and description
salience_score_minfloatNoMinimum salience score
salience_score_maxfloatNoMaximum salience score
article_count_minintegerNoMinimum number of source articles (≥ 0)
article_count_maxintegerNoMaximum number of source articles (≥ 0)
actor_count_minintegerNoMinimum number of actors involved (≥ 0)
actor_count_maxintegerNoMaximum number of actors involved (≥ 0)
sort_bystringNoSort column: event_date (default), salience_score, article_count, title, created_at
sort_orderstringNoSort direction: asc or desc (default: desc)
Note on sort_by: Unrecognised values silently fall back to event_date. No validation error is returned. Note on categorical filters: Passing an unknown value (e.g. an unrecognised event_category) returns an empty result set, not a 422 error.

​
Response

{
  "items": [
    {
      "id": "ad8b3d2a-353f-41fd-908d-780615f31673",
      "title": "Armed clash in Borno State",
      "description": "Clashes erupted between Nigerian military and insurgent forces...",
      "eventCategory": "conflict",
      "eventType": "battles",
      "eventSubtype": "armed_clash",
      "eventDate": "2026-02-10",
      "eventDateEnd": null,
      "location": "Maiduguri",
      "locationCountry": "NG",
      "locationCoordinates": {
        "lat": 11.8311,
        "lng": 13.4302
      },
      "fatalities": 15,
      "injuries": 23,
      "abductions": 0,
      "civilianTargeting": false,
      "admin1": "Borno",
      "admin2": "Maiduguri",
      "admin3": null,
      "geoPrecision": 1,
      "salienceScore": 0.85,
      "articleCount": 3,
      "actorCount": 2,
      "sourceDomains": ["reuters.com", "bbc.co.uk"],
      "sourceTypes": ["news"],
      "createdAt": "2026-02-10T14:30:00Z",
      "updatedAt": "2026-02-10T14:30:00Z"
    }
  ],
  "total": 6677,
  "page": 1,
  "pageSize": 50,
  "totalPages": 134
}

​
Event Fields

FieldTypeDescription
idUUIDUnique event identifier
titlestringEvent title/headline
descriptionstringDetailed event description (nullable)
eventCategorystringCategory ID (e.g., “conflict”, “cyber”)
eventTypestringType ID within category
eventSubtypestringSubtype ID within type (nullable)
eventDatedateDate when the event occurred, YYYY-MM-DD (nullable)
eventDateEnddateEnd date for multi-day events (nullable)
locationstringSpecific location name (nullable)
locationCountrystringISO 3166-1 alpha-2 country code (nullable)
locationCoordinatesobjectObject with lat and lng floats (nullable)
fatalitiesintegerNumber of reported fatalities (nullable)
injuriesintegerNumber of reported injuries (nullable)
abductionsintegerNumber of reported abductions (nullable)
civilianTargetingbooleanWhether civilians were deliberately targeted (nullable)
admin1stringFirst-level administrative division, e.g. state/province (nullable)
admin2stringSecond-level administrative division, e.g. district/county (nullable)
admin3stringThird-level administrative division, e.g. commune/ward (nullable)
geoPrecisionintegerGeographic precision level: 1=exact/rooftop, 2=district/city, 3=approximate/country (nullable)
salienceScorefloatRelevance/importance score 0.0–1.0 (nullable)
articleCountintegerNumber of source articles
actorCountintegerNumber of actors involved
sourceDomainsstring[]Source domains where event was reported (nullable)
sourceTypesstring[]Source/article types contributing to this event: news, government_report, academic, court_document, press_release, blog, social_media, archive, other (nullable)
createdAtdatetimeWhen the record was created
updatedAtdatetimeWhen the record was last updated

​
Example Requests

# Conflict events in Nigeria since 2025, sorted by salience
curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events?event_category=conflict&country=NG&date_from=2025-01-01&sort_by=salience_score&sort_order=desc"

# Multiple categories and countries
curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events?event_category=conflict&event_category=crime&country=UA&country=RU"

# High-salience events with at least 3 source articles
curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events?salience_score_min=0.7&article_count_min=3&sort_by=salience_score&sort_order=desc"

# Full-text search
curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events?search=ransomware+attack&event_category=cyber"

​
See Also

  • Get Event - Full event detail including category-specific data
  • Export Events - Bulk export in CSV, JSON, GeoJSON, ACLED, or flat format
  • Event Taxonomy - Valid category, type, and subtype values