Consent Manager

  • Your Privacy

  • Strictly Necessary Cookies

  • Performance Cookies

  • Targeting Cookies

  • Functional Cookies

Your Privacy

When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer. For more information on the information we collect and how we use it see the Website Privacy Statement.

Strictly Necessary Cookies

Always Active

These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.

Performance Cookies

Off On

These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.

Targeting Cookies

Off On

These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising.

Functional Cookies

These cookies enable the website to provide enhanced functionality and personalization. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.

Your Privacy [`dialog closed`]

By continuing to use our website, you acknowledge the use of cookies. Privacy Statement | Change Settings

Cookies allow us to optimise your use of our website. We also use third-party cookies for advertising and analytics. Please read our Privacy Statement and Website Privacy Statement for more information on how we use cookies.

This is a preview of our upcoming API version 7, subject to change without notice.

DEVELOPER REFERENCE

Search Results

×Clear

  • Overview
    • Welcome
    • Authentication
    • Account group context
    • Response formats
    • Time ranges
    • Response status codes
    • Rate limits
    • Pagination
    • Change policy
    • API change summary

  • Administrative API
    • Administrative API

  • Alerts & Notifications
    • Active alerts
    • Alert details

  • BGP Monitors
    • BGP Monitors

  • Dashboards
    • Dashboard list
    • Dashboard detail
    • Dashboard widget data
    • Creating a dashboard
    • Updating a dashboard
    • Deleting a dashboard
    • Dashboard snapshots list
    • Dashboard snapshot detail
    • Dashboard snapshot data
    • Creating a dashboard snapshot
    • Deleting a dashboard snapshot
    • Update a snapshot

  • Internet Insights
    • Outages

  • Tags
    • Tags

  • Test Data
    • (Network) Path visualization

  • Test Template
    • Test Template

  • ThousandEyes for OpenTelemetry
    • ThousandEyes for OpenTelemetry
  • APIv6  |  Showing APIv7 (preview)
  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository
Try ThousandEyes Now! Sign Up

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 {email}:{authToken}

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
alertIdstringn/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)
severitystringn/afield with one of the following values: INFO, MAJOR, MINOR, CRITICAL for all alert types

Header

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", "severity": "INFO" }, { "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", "severity": "INFO" } ] }

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 {email}:{authToken}

$ curl https://api.thousandeyes.com/v7/alerts/http-server/1000002 \ -u {email}:{authToken}

$ curl https://api.thousandeyes.com/v7/alerts/network-outage/1000003 \ -u {email}:{authToken}

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)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)stringn/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
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-outage and application-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 and application-outage)integern/anumber of sources currently meeting the alert criteria
applicationNameapplication-outagestringn/aname of the affected application
severity(all)stringn/afield with one of the following values: INFO, MAJOR, MINOR, CRITICAL for all alert types

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
http-serverCEATestsWeb / HTTP Server
page-loadCEATestsWeb / Page Load
web-transactionCEATestsWeb / Transaction
ftp-serverCEATestsWeb / FTP Server
voiceCEATestsVoice / RTP Stream
sip-serverCEATestsVoice / SIP Server
network-outageII*-Network outage
application-outageII*-Application 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)

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)

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

FieldData TypeUnitsNotes
affectedServersCountintegern/anumber of servers affected 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

Header

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, "severity": "INFO" }

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", "severity": "INFO" }

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, "severity": "INFO" }

Body - with application outage locations

{ "alertId": "35085", "alertType": "application-outage", "apiLinks": [ { "href": "https://api.thousandeyes.com/v7/alerts/application-outage/35085", "rel": "self" } ], "applicationName": "Paypal", "dateStart": "2020-04-13 16:20:00", "locations": [ { "affectedServersCount": 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=35085&locationId=2925533" }, { "affectedServersCount": 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=35085&locationId=4180439" }, ... ], "permalink": "https://app.thousandeyes.com/alerts/list/?__a=11&alertId=35085", "ruleId": 2021, "state": "ACTIVE", "severity": "INFO" }

For error responses, see the response status codes documentation.

© 2023 ThousandEyes. All rights reserved.