IODA's Alert API allows users to query for outage alerts generated by IODA. An outage alert signifies the beginning or end of a potential outage event.
Outage alerts are generated by IODA using three data sources—Internet Background Radiation (IBR), BGP, and active probing. For more information about the detection methodology see the Help page. Alerts are generated by IODA when there is a significant drop (or 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 help page contains more details on how IODA generates alerts for each of its data sources.
IODA’s Alert API has been designed to allow users to query for subsets of outage alerts that users are interested in. Instead of retrieving all outage alerts that IODA has ever generated, users will typically be interested in specific subsets of alerts. For instance, users may seek only the alerts that affect a specific country or Autonomous System, or alerts that were generated 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 alerts using the IODA Alert API below, but for a detailed technical description of the API endpoints, parameters and responses please refer to the auto-generated Swagger (OpenAPI) Documentation.
The Alert API allows a user to specify the time range in which they are
interested, using the from and until parameters.
The response will
include alerts that were generated during the user-specified time range.
The from and until parameters should both be
provided in Unix Epoch seconds.
For example, the following GET request will return all alerts generated by IODA between 10:00:00 to 11:00:00 on Jan 10, 2019:
GET https://ioda.caida.org/ioda/data/alerts?from=1547114400&until=1547118000&annotateMeta=true&human=true {
"type": "watchtower.alerts",
"error": null,
"queryParameters": {
...
},
"data": {
"alerts": [
{
...
"name": "BGP \/24s (min 50% ff-peer-ASNs)",
"time": 1547117700,
"level": "warning",
...
"condition": "\u003C historical * 0.99",
"value": 38,
"historyValue": 40,
"metaType": "asn",
"metaCode": "23657",
"meta": {
"name": "AS23657 (Blue Sky Communications)",
"attrs": {
"fqid": "asn.23657",
"org": "Blue Sky Communications",
"ip_count": "9728",
"name": "BLUESKY-AS-AP"
}
}
},
...
]
}
}
Users can specify the geographic region or Autonomous System they seek
using the meta parameter and the API will return the relevant subset
of alerts. Each alert generated by IODA includes a meta field that indicates
the group of addresses that the alert 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 alerts affecting
Autonomous Systems can set meta=asn and the API will return all such alerts. Further, setting
meta=country/<country-code>, meta=region/<region-code>, meta=asn/<Autonomous-System-Number> allows users to view only the subset of
alerts affecting the user-specified group of addresses.
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 alerts for all (any) countries, the meta parameter should be
set to country (i.e., meta=country).
To request alerts 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 alerts generated in the U.S. between 10:00:00 to 11:00:00 on Jan 10, 2019:
GET https://ioda.caida.org/ioda/data/alerts?from=1547114400&until=1547118000&annotateMeta=true&human=true&meta=country/US{
"type": "watchtower.alerts",
"error": null,
"queryParameters": {
...
},
"data": {
"alerts": [
{
...
"name": "BGP \/24s (min 50% ff-peer-ASNs)",
"time": 1547116200,
"level": "warning",
...
"condition": "\u003C historical * 0.99",
"value": 3893137,
"historyValue": 3951735.5,
"metaType": "country",
"metaCode": "US",
"meta": {
"name": "United States",
"attrs": {
"fqid": "geo.netacuity.NA.US"
}
}
}
]
}
}To request alerts 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 the next version of this API.
The API allows users to specify which Autonomous Systems they seek, also
using the meta parameter.
Similarly to country, alerts for all (any) ASNs can be retrieved by
setting the meta parameter to asn (meta=asn).
To request alerts 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 alerts generated in AS 3307 between 10:00:00 to 11:00:00 on Jan 10, 2019::
GET https://ioda.caida.org/ioda/data/alerts?from=1547114400&until=1547118000&annotateMeta=true&human=true&meta=asn/3307{
"type": "watchtower.alerts",
"error": null,
"queryParameters": {
...
},
"data": {
"alerts": [
{
...
"name": "BGP \/24s (min 50% ff-peer-ASNs)",
"time": 1547117700,
"level": "critical",
...
"condition": "\u003C historical * 0.5",
"value": 0,
"historyValue": 1,
"metaType": "asn",
"metaCode": "3307",
"meta": {
"name": "AS3307 (Broadnet AS)",
"attrs": {
"fqid": "asn.3307",
"org": "Broadnet AS",
"ip_count": "256",
"name": "BANETELE-NORWAY"
}
}
}
]
}
}