Event API

IODA's Event API allows users to query for outage events detected by IODA. An outage event is an instance of a macroscopic Internet outage affecting the edge of the network. Each event has well-defined fields, such as the outage's start-time, duration and other fields, as defined in the Common Outage Data Format.

IODA detects outage events using three data sources—Internet Background Radiation (IBR), BGP, and active probing. For more information about the detection methodology see the Help page. Events are detected by IODA when there is a significant drop followed by a subsequent increase in the timeseries of an IODA data source for a group of addresses (such as addresses belonging to the same geographic region or Autonomous System).

IODA’s Event API has been designed to allow users to query for subsets of outage events that users are interested in. Instead of retrieving all outage events that IODA has ever detected, users will typically be interested in specific subsets of events. For instance, users may seek only the events that affect a specific country or Autonomous System, or events that were detected during specific periods. In fact, we highly recommend that users use the available filter parameters to limit the number of results that are returned by the API.

We describe different ways to retrieve various subset(s) of outage events using the IODA Event API below, but for a detailed technical description of the API endpoints, parameters and responses please refer to the auto-generated Swagger (OpenAPI) Documentation.

Finding Events By Time

The Event API allows a user to specify the time range in which they are interested, using the from and until parameters. The response will include events that were detected during the user-specified time range (we discuss the set of returned events in further detail, along with edge cases, below). The from and until parameters should both be provided in Unix Epoch seconds.

For example, the following GET request will return all events detected by IODA between 20:00:00 to 23:00:00 on June 26, 2019:

GET https://ioda.caida.org/ioda/data/events?from=1561579200&until=1561590000&human=true 
{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
    ...
    },
    "data": {
        "events": [
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "asn.62196",
                "start": 1561579800,
                "duration": 6300,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 5250,
                "location_type": "asn",
                "location_code": "62196",
                "location_name": "AS62196 (Rayan Ravesh Sena Ltd)",
                "overlaps_window": false
            },	
	...
            {
                "datasource": "active.ping-slash24.team-1.up_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561579800,
                "duration": 7800,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 6461.9668664082,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            },	
	...
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561579800,
                "duration": 6300,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 4166.6918087193,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            },	
	...
	]
    }
}

Caveats

Since the Event API is constructed from the underlying Alert API, there are some edge-cases where the event API’s results can be counterintuitive.

The API works exactly as expected for events that have both a start-time and end-time that lie within the specified time range. For example, consider the following GET request, which will return all events detected by IODA between 20:00:00 to 23:00:00 on June 26, 2019 in Iran (we discuss how to obtain events by specific geographic regions and ASNs in more detail below):

GET https://ioda.caida.org/ioda/data/events?from=1561579200&until=1561590000&human=true&meta=country/IR 
{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
    ...
    },
    "data": {
        "events": [
            {
                "datasource": "active.ping-slash24.team-1.up_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561579800,
                "duration": 7800,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 6461.9668664082,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            },	
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561579800,
                "duration": 6300,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 4166.6918087193,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            },
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561586700,
                "duration": 1500,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 28.015430036851,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            }
	]
    }
}
All three events returned by the query have their start-times after the from parameter and their end-times before the until parameter.

Edge-cases

Counterintuitive results can be returned when an event lies within the specified time-range but also lies partially outside. We describe the three different scenarios in which events can lie partially outside the specified time-range and the behavior of the API for each below.

Event begins in the specified time-range, but ends after

When this scenario occurs, the API returns the event; however, its duration is truncated (the event appears to end at the specified until time).

Modifying the GET request to query for the events detected by IODA between 20:00:00 to 22:00:00 on June 26, 2019 in Iran, we see:

GET https://ioda.caida.org/ioda/data/events?from=1561579200&until=1561586400&human=true&meta=country/IR 
{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
    ...
    },
    "data": {
        "events": [
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561579800,
                "duration": 6300,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 4166.6918087193,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            },
            {
                "datasource": "active.ping-slash24.team-1.up_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561579800,
                "duration": 6600,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 5467.81811773,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": true
            }
	]
    }
}
We observe that the two events which have a start-time within the specified interval are returned by this query; however, the duration of the event beginning at 1561579800 (20:10:00 on June 26, 2019) has now been truncated to 6600 seconds whereas the duration of the other event (whose end-time falls before the until parameter) remains unchanged. In addition, the overlaps_window field has been set to "true" for the former event, to indicate that its duration has been truncated.

Event begins before, but ends within the specified time-range

When this scenario occurs, the API does not return the event.

Modifying the GET request to query for the events detected by IODA between 21:00:00 to 23:00:00 on June 26, 2019 in Iran, we see:

GET https://ioda.caida.org/ioda/data/events?from=1561582800&until=1561590000&human=true&meta=country/IR 
{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
    ...
    },
    "data": {
        "events": [
            {
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "geo.netacuity.AS.IR",
                "start": 1561586700,
                "duration": 1500,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 28.015430036851,
                "location_type": "country",
                "location_code": "IR",
                "location_name": "Iran (Islamic Republic Of)",
                "overlaps_window": false
            }    
	]
    }
}
We observe that the two events which had started at 1561579800 (20:10:00 on June 26, 2019) are not returned even though they ended before the until parameter since these events started before the from parameter.

Event begins before the specified time-range and ends after

When this scenario occurs, the API does not return the event.

Modifying the GET request to query for the events detected by IODA between 21:00:00 to 22:00:00 on June 26, 2019 in Iran, we see:

GET https://ioda.caida.org/ioda/data/events?from=1561582800&until=1561586400&human=true&meta=country/IR
{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
    ...
    },
    "data": {
        "events": []
    }
}
We observe that the two events which had started at 1561579800 (20:10:00 on June 26, 2019), spanned the entirety of the specified interval and ended after, are not returned.

Finding Events By Geographic Region or ASN

Users can specify the geographic region or Autonomous System they seek using the meta parameter and the API will return the relevant subset of events. Each event detected by IODA includes a meta field that indicates the group of addresses that the event affects: the group may be addresses geolocating to a country, addresses geolocating to a region within a country, or addresses belonging to a specific Autonomous System. Users who would like to see only events affecting Autonomous Systems can set meta=asn and the API will return all such events. Further, setting meta=country/<country-code>, meta=region/<region-code>, meta=asn/<Autonomous-System-Number> allows users to view only the subset of events affecting the user-specified group of addresses.

Geographic Region (Country)

The API supports two levels of granularity for geographic regions: country and administrative regions within countries (like states in the U.S. or provinces in Canada).

To request events for all (any) countries, the meta parameter should be set to country (i.e., meta=country).

To request events for a specific country, the meta parameter should be set to country/<2-letter-ISO-country-code>. For example, meta=country/US.

For example, the following GET request will return events detected in the U.S. between 10:00:00 to 11:00:00 on Jan 10, 2019:

GET https://ioda.caida.org/ioda/data/events?from=1547114400&until=1547118000&human=true&meta=country/US
{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
	...
    },
    "data": {
        "events": [
            {
                "datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
                "location": "geo.netacuity.NA.US",
                "start": 1547116200,
                "duration": 1800,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 44.485644345377,
                "location_type": "country",
                "location_code": "US",
                "location_name": "United States",
                "overlaps_window": true
            }	
        ]
    }
}

To request events for specific geographic regions, users need to know the identifier for the region that IODA uses internally. We plan to expose the ability to query for specific regions in a future version.

Autonomous System (AS)

The API allows users to specify which Autonomous Systems they seek, also using the meta parameter.

Similarly to country, events for all (any) ASNs can be retrieved by setting the meta parameter to asn (meta=asn).

To request events for a specific Autonomous System, the meta parameter should be set to asn/<Autonomous-System-Number>. For example, meta=asn/3307.

For example, the following GET request will return events detected in AS 3307 between 10:00:00 to 11:00:00 on Jan 10, 2019::

GET https://ioda.caida.org/ioda/data/events?from=1547114400&until=1547118000&human=true&meta=asn/3307

{
    "type": "watchtower.events",
    "error": null,
    "queryParameters": {
        ...
    },
    "data": {
        "events": [
            {
                "location": "asn.3307",
                "start": 1547117700,
                "duration": 300,
                "uncertainty": null,
                "status": 0,
                "fraction": null,
                "score": 500,
                "location_type": "asn",
                "location_code": "3307",
                "location_name": "AS3307 (Broadnet AS)",
                "overlaps_window": true
            }
        ]
    }
}