This is a preview of our upcoming API version 7, subject to change without notice.
At this time, APIv6 is the recommended API version to use.

Alerts & Notifications

GET /v7/alerts Active alerts

Returns a list of all active alerts, or alerts that started within a given time range.

Optional (Querystring) Parameters

  • window=[0-9]+[smhdw]? specifies a window of time for the result set. See Time Ranges for more information.
  • from=YYYY-mm-ddTHH:MM:SS&to=YYYY-mm-ddTHH:MM:SS specifies an explicit start (and optionally, end) for your range of data. See Time Ranges for more information.
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v7/alerts \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of presently active alerts, or alerts that became active during the time range specified. If the specific time range is requested, only the alerts that have triggered in that time range will be returned. If no alerts were triggered during the time range specified, an empty response will be returned.

FieldData TypeUnitsNotes
alertIdintegern/aunique ID of the alert; each alert occurrence is assigned a new unique ID
alertTypestringn/atype of alert being triggered. In multi-layered tests, this value represents the layer the alert relates to. See Alert Details documentation for a list of possible values
apiLinksarray of linksn/alist of hyperlinks to other areas of the API
dateStartdateTimeyyyy-MM-dd hh:mm:ssthe date/time where an alert rule was triggered, expressed in UTC
dateEnddateTimeyyyy-MM-dd hh:mm:ssthe date/time where the alert has cleared, expressed in UTC
permalinkstringn/ahyperlink to alerts list, with row expanded
ruleIdintegern/aunique ID of the alert rule (see /alert-rules endpoint for more detail)
statestringn/acurrent state of the alert. Possible values: ACTIVE, CLEARED, or DISABLED (when the test is deleted or disabled, or when the alert rule is deleted or disassociated from the test)

HTTP/1.1 200 OK Date: Thu, 23 Apr 2020 13:09:28 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1587647400 Strict-Transport-Security: max-age=31536000

Body

{ "alerts": [ { "alertId": 2556232, "alertType": "http-server", "apiLinks": [ { "href": "https://api.thousandeyes.com/v7/alerts/http-server/2556232", "rel": "self" }, { "href": "https://api.thousandeyes.com/v6/alert-rules/289585.json", "rel": "rule" } ], "dateStart": "2020-04-23 13:43:16", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=7625&alertId=2556232", "ruleId": 289585, "state": "ACTIVE" }, { "alertId": 2257070, "alertType": "network-outage", "apiLinks": [ ... ], "dateStart": "2020-02-20 07:45:00", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=7625&alertId=2257070", "ruleId": 186333, "state": "ACTIVE" } ] }

For error responses, see the response status codes documentation.

GET /v7/alerts/{alertType}/{alertId} Alert details

Returns details about an alert. The {alertType} value in URL must match specific alert’s type.

Optional (Querystring) Parameters

  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information

Request

  • no request body

Example requests

$ curl https://api.thousandeyes.com/v7/alerts/bgp/1000001 \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

$ curl https://api.thousandeyes.com/v7/alerts/http-server/1000002 \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

$ curl https://api.thousandeyes.com/v7/alerts/network-outage/1000003 \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

$ curl https://api.thousandeyes.com/v7/alerts/dnsp-domain/1000004 \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back detailed information about a specific alertId. If the alertId doesn’t exist or is inaccessible by your account, an empty response will be returned.

FieldFor alert typeData TypeUnitsNotes
agentsCEA* (except bgp and dnsp-*)array of agent objectsn/aarray of agents where the alert has at some point been active since the point that the alert was triggered
alertId(all)integern/aunique ID of the alert; each alert occurrence is assigned a new unique ID
alertType(all)stringn/atype of alert being triggered. In multi-layered tests, this value represents the layer the alert relates to
apiLinks(all)array of linksn/alist of hyperlinks to other areas of the API
asNamenetwork-outagestringn/aname of the Autonomous System
asnnetwork-outageintegern/anumber of the Autonomous System
countriesdnsp-*array of country objectsn/aarray of countries with DNS servers participating in the alert
dateEnd(all)dateTimeyyyy-MM-dd hh:mm:ssthe date/time when the alert has cleared, expressed in UTC
dateStart(all)dateTimeyyyy-MM-dd hh:mm:ssthe date/time when an alert rule was triggered, expressed in UTC
locationsnetwork-outagearray of location objectsn/aarray of locations participating in an outage. Each entry represents a 5-minute interval, meaning if the same location is recognized as affected in two consecutive 5-minute rounds, two entries for the same location will be present in this array, with different dateAffected values
monitorsbgparray of monitor objectsn/aarray of monitors where the alert has at some point been active since the point that the alert was triggered. Only shown on BGP alerts.
permalink(all)stringn/ahyperlink to alerts list, with row expanded
ruleId(all)integern/aunique ID of the alert rule (see /alert-rules endpoint for more detail)
state(all)stringn/acurrent state of the alert. Possible values: ACTIVE, CLEARED, or DISABLED (when the test is deleted or disabled, or when the alert rule is deleted or disassociated from the test)
testIdCEAintegern/aunique ID of the test (see /tests/{testId} endpoint for more detail)
violationCount(all except network-outage)integern/anumber of sources currently meeting the alert criteria

Abbreviations used in the table above: * CEA: Cloud & Enterprise Agent-related tests

The alertType field will contain one of the following values:

alertTypePlatform areaEntityRelated test layer/type or additional notes
bgpCEA*TestsRouting / BGP
path-traceCEATestsNetwork / Path visualization data
end-to-end-serverCEATestsNetwork / Agent to Server
end-to-end-agentCEATestsNetwork / Agent to Agent
dns-serverCEATestsDNS / DNS Server
dns-traceCEATestsDNS / DNS Trace
dns-dnssecCEATestsDNS / DNSSEC
dnsp-domainCEATestsDNS+ / DNS+ Domain
dnsp-serverCEATestsDNS+ / DNS+ Server
http-serverCEATestsWeb / HTTP Server
page-loadCEATestsWeb / Page Load
transactionCEATestsWeb / Transaction (Classic)
web-transactionCEATestsWeb / Transaction
ftp-serverCEATestsWeb / FTP Server
voiceCEATestsVoice / RTP Stream
sip-serverCEATestsVoice / SIP Server
network-outageII*-Network outage

Abbreviations used in the table above:

  • CEA: Cloud & Enterprise Agents
  • II: Internet Insights

Agent objects (see above) reflect the following content:

FieldData TypeUnitsNotes
agentIdintegern/aunique ID of agent or monitor violating the alert rule. See /agents for more detail
agentNamestringn/adisplay name of the agent violating the alert rule
dateEnddateTimeyyyy-MM-dd hh:mm:ssreflects the earlier of the date that the alert was cleared, or the source reported a measurement that was under the alert rule’s threshold, expressed in UTC
dateStartdateTimeyyyy-MM-dd hh:mm:ssreflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold, expressed in UTC
metricsAtEndstringn/astring representation of the metric or metrics being considered in the alert rule at the point that the alert was cleared. If the alert is not yet cleared, this field reflects the last round of data gathered from the source.
metricsAtStartstringn/astring representation of the metric at the time that the source began alerting. Note that the alert start and dateStart for a particular source do not need to be the same, as sources may change alerting status throughout an alert’s lifecycle
permalinkstringn/ahyperlink to alerts list, with row expanded
statestringn/acurrent state of the alert for this agent. Possible values: ACTIVE, CLEARED, or DISABLED (when the test is deleted or disabled, or when the alert rule is deleted or disassociated from the test)

Country objects (available for dnsp-* alert types only, see above) reflect the following content:

FieldData TypeUnitsNotes
countryIdstringn/aISO 3166-1 alpha-2 code of country containing DNS servers violating the alert rule
dateEnddateTimeyyyy-MM-dd hh:mm:ssreflects the earlier of the date that the alert was cleared, or the source reported a measurement that was under the alert rule’s threshold, expressed in UTC
dateStartdateTimeyyyy-MM-dd hh:mm:ssreflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold, expressed in UTC
metricsAtEndstringn/astring representation of the metric or metrics being considered in the alert rule at the point that the alert was cleared. If the alert is not yet cleared, this field reflects the last round of data gathered from the source.
metricsAtStartstringn/astring representation of the metric at the time that the source began alerting. Note that the alert start and dateStart for a particular source do not need to be the same, as sources may change alerting status throughout an alert’s lifecycle
permalinkstringn/ahyperlink to alerts list, with row expanded
statestringn/acurrent state of the alert for this location. Possible values: ACTIVE, CLEARED, or DISABLED (when the test is deleted or disabled, or when the alert rule is deleted or disassociated from the test)
vantagePointsintegern/anumber of DNS servers violating the alert rule

Location objects (available for network-outage alert type only, see above) reflect the following content:

FieldData TypeUnitsNotes
affectedInterfacesCountintegern/anumber of affected router interfaces by this outage
affectedTestsarray of integersn/aarray of affected testIds in the current account group
affectedTestsCountintegern/anumber of affected tests in the current account group
dateAffecteddateTimeyyyy-MM-dd hh:mm:ssreflects the start date/time of the 5-minute interval when the location was recognized as affected, expressed in UTC.
locationIdintegern/anumeric location identifier. The number is chosen internally for each location by ThousandEyes, and will not change
locationNamestringn/atextual location identifier
permalinkstringn/ahyperlink to alerts list, with row expanded

Monitor objects (available for bgp alert type only, see above) reflect the following content:

FieldData TypeUnitsNotes
asNamestringn/aname of the monitor’s home Autonomous System
asnintegern/anumber of the monitor’s home Autonomous System
dateEnddateTimeyyyy-MM-dd hh:mm:ssreflects the earlier of the date that the alert was cleared, or the source reported a measurement that was under the alert rule’s threshold, expressed in UTC
dateStartdateTimeyyyy-MM-dd hh:mm:ssreflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold, expressed in UTC
metricsAtEndstringn/astring representation of the metric or metrics being considered in the alert rule at the point that the alert was cleared. If the alert is not yet cleared, this field reflects the last round of data gathered from the source.
metricsAtStartstringn/astring representation of the metric at the time that the source began alerting. Note that the alert start and dateStart for a particular source do not need to be the same, as sources may change alerting status throughout an alert’s lifecycle
monitorIdintegern/aunique ID of monitor violating the alert rule. See /bgp-monitors for more detail
monitorNamestringn/adisplay name of the monitor violating the alert rule
permalinkstringn/ahyperlink to alerts list, with row expanded
prefixstringn/anetwork prefix affected, expressed as a.b.c.d/e (or IPv6 equivalent)
prefixIdintegern/anumeric prefix identifier. The number is chosen internally for each prefix by ThousandEyes, and will not change
statestringn/acurrent state of the alert for this monitor. Possible values: ACTIVE, CLEARED, or DISABLED (when the test is deleted or disabled, or when the alert rule is deleted or disassociated from the test)

HTTP/1.1 200 OK Date: Thu, 23 Apr 2020 13:09:28 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1587647400 Strict-Transport-Security: max-age=31536000

Body - with agents

{ "agents": [ { "agentId": 813, "dateEnd": "2020-04-23 13:44:18", "dateStart": "2020-04-23 13:43:16", "metricsAtEnd": "Error: \"\"", "metricsAtStart": "Error: \"500 Internal Server Error\"", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=7625&alertId=2556232&agentId=813", "state": "CLEARED" }, ... ], "alertId": 2556232, "alertType": "http-server", "apiLinks": [ { "href": "https://api.thousandeyes.com/v7/alerts/http-server/2556232", "rel": "self" }, { "href": "https://api.thousandeyes.com/v6/alert-rules/289585.json", "rel": "rule" }, { "href": "https://api.thousandeyes.com/v6/tests/83126.json", "rel": "related" }, { "href": "https://api.thousandeyes.com/v6/web/http-server/83126.json", "rel": "data" } ], "dateEnd": "2020-04-23 13:44:18", "dateStart": "2020-04-23 13:43:16", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=7625&alertId=2556232", "ruleId": 289585, "state": "CLEARED", "testId": 83126, "violationCount": 1 }

Body - with countries

{ "alertId": 1178025, "alertType": "dnsp-domain", "apiLinks": [ { "href": "https://api.thousandeyes.com/v7/alerts/dnsp-domain/1178025", "rel": "self" }, { "href": "https://api.thousandeyes.com/v6/alert-rules/190752.json", "rel": "rule" }, { "href": "https://api.thousandeyes.com/v6/tests/9212.json", "rel": "related" }, { "href": "https://api.thousandeyes.com/v6/dnsp/availability/9212.json", "rel": "data" }, { "href": "https://api.thousandeyes.com/v6/dnsp/resolution-time/9212.json", "rel": "data" }, { "href": "https://api.thousandeyes.com/v6/dnsp/mappings/9212.json", "rel": "data" } ], "countries": [ { "countryId": "AU", "dateStart": "2019-01-09 00:00:01", "metricsAtEnd": "", "metricsAtStart": "Availability: 100%, Reference Availability: 100%", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=1178025&countryId=AU", "state": "ACTIVE", "vantagePoints": 50 }, { "countryId": "BR", "dateStart": "2019-01-09 00:00:01", "metricsAtEnd": "", "metricsAtStart": "Availability: 100%, Reference Availability: 100%", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=1178025&countryId=BR", "state": "ACTIVE", "vantagePoints": 34 }, ... ], "dateStart": "2019-01-09 00:00:06", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=1178025", "ruleId": 190752, "state": "ACTIVE", "testId": 9212, "violationCount": 20 }

Body - with network outage locations

{ "alertId": 2542187, "alertType": "network-outage", "apiLinks": [ { "href": "https://api.thousandeyes.com/v7/alerts/network-outage/2542187", "rel": "self" } ], "asName": "Level 3 Communications, Inc.", "asn": 3356, "dateStart": "2020-04-13 16:20:00", "locations": [ { "affectedInterfacesCount": 2, "affectedTests": [ 12123 ], "affectedTestsCount": 1, "dateAffected": "2020-04-13 16:20:00", "locationId": 2925533, "locationName": "Frankfurt am Main, Germany", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=2542187&locationId=2925533" }, { "affectedInterfacesCount": 1, "affectedTests": [ 12123 ], "affectedTestsCount": 1, "dateAffected": "2020-04-13 16:20:00", "locationId": 4180439, "locationName": "Atlanta, Georgia, US", "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=2542187&locationId=4180439" }, ... ], "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=2542187", "ruleId": 289901, "state": "ACTIVE" }

Body - with BGP monitors

{ "alertId": 314935, "alertType": "bgp", "apiLinks": [ { "href": "https://api.thousandeyes.com/v7/alerts/bgp/314935", "rel": "self" }, ... ], "dateStart": "2017-10-06 18:15:00", "monitors": [ { "asName": "Elisa Oyj", "asn": 6667, "dateStart": "2018-08-26 18:00:00", "metricsAtEnd": "", "metricsAtStart": "Reachability: 99.8%", "monitorId": 53, "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=314935&monitorId=53", "prefix": "93.168.254.0/23", "prefixId": 610088, "state": "ACTIVE" }, { "asName": "ColocationIX GmbH", "asn": 61955, "dateStart": "2020-04-07 17:15:00", "metricsAtEnd": "", "metricsAtStart": "Reachability: 0%", "monitorId": 4131, "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=314935&monitorId=4131", "prefix": "93.168.254.0/23", "prefixId": 610088, "state": "ACTIVE" }, ... ], "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=314935", "ruleId": 75409, "state": "ACTIVE", "testId": 25611, "violationCount": 86 }

For error responses, see the response status codes documentation.