List Events
Query events with filtering, pagination, and sorting
GET
/
v1
/
events
List Events
curl --request GET \
--url https://api.example.com/v1/eventsimport requests
url = "https://api.example.com/v1/events"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v1/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/events"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/events")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyReturns a paginated list of events. Categorical filters accept multiple values by repeating the parameter.
Note on
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number, starting at 1 (default: 1) |
page_size | integer | No | Results per page, 1–500 (default: 50) |
event_category | string[] | No | Filter by event category (repeatable) |
event_type | string[] | No | Filter by event type within category (repeatable) |
event_subtype | string[] | No | Filter by event subtype (repeatable) |
country | string[] | No | Filter by country code (repeatable) |
date_from | string | No | Inclusive start date (YYYY-MM-DD) |
date_to | string | No | Inclusive end date (YYYY-MM-DD) |
search | string | No | Full-text search across title and description |
salience_score_min | float | No | Minimum salience score |
salience_score_max | float | No | Maximum salience score |
article_count_min | integer | No | Minimum number of source articles (≥ 0) |
article_count_max | integer | No | Maximum number of source articles (≥ 0) |
actor_count_min | integer | No | Minimum number of actors involved (≥ 0) |
actor_count_max | integer | No | Maximum number of actors involved (≥ 0) |
sort_by | string | No | Sort column: event_date (default), salience_score, article_count, title, created_at |
sort_order | string | No | Sort direction: asc or desc (default: desc) |
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
| Field | Type | Description |
|---|---|---|
id | UUID | Unique event identifier |
title | string | Event title/headline |
description | string | Detailed event description (nullable) |
eventCategory | string | Category ID (e.g., “conflict”, “cyber”) |
eventType | string | Type ID within category |
eventSubtype | string | Subtype ID within type (nullable) |
eventDate | date | Date when the event occurred, YYYY-MM-DD (nullable) |
eventDateEnd | date | End date for multi-day events (nullable) |
location | string | Specific location name (nullable) |
locationCountry | string | ISO 3166-1 alpha-2 country code (nullable) |
locationCoordinates | object | Object with lat and lng floats (nullable) |
fatalities | integer | Number of reported fatalities (nullable) |
injuries | integer | Number of reported injuries (nullable) |
abductions | integer | Number of reported abductions (nullable) |
civilianTargeting | boolean | Whether civilians were deliberately targeted (nullable) |
admin1 | string | First-level administrative division, e.g. state/province (nullable) |
admin2 | string | Second-level administrative division, e.g. district/county (nullable) |
admin3 | string | Third-level administrative division, e.g. commune/ward (nullable) |
geoPrecision | integer | Geographic precision level: 1=exact/rooftop, 2=district/city, 3=approximate/country (nullable) |
salienceScore | float | Relevance/importance score 0.0–1.0 (nullable) |
articleCount | integer | Number of source articles |
actorCount | integer | Number of actors involved |
sourceDomains | string[] | Source domains where event was reported (nullable) |
sourceTypes | string[] | Source/article types contributing to this event: news, government_report, academic, court_document, press_release, blog, social_media, archive, other (nullable) |
createdAt | datetime | When the record was created |
updatedAt | datetime | When 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
⌘I
List Events
curl --request GET \
--url https://api.example.com/v1/eventsimport requests
url = "https://api.example.com/v1/events"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v1/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/events"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/events")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body