Alerts

`GET /v5/alert-rules` Alert Rules

Returns a list of all alert rules configured under your account in ThousandEyes.

Optional Parameters

format=json|xml optional, specifies the format of output requested. See Output Formats for more information
aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

no request body

Example

$curl https://api.thousandeyes.com/v5/alert-rules.json \ -u {email}:{authToken}

Response

Sends back an array of alert rules, indicating ruleID, whether or not the alert is enabled, recipient lists, and the rule criteria and clearing logic. Default rules for each type are indicated with a bit response (1 or 0); default alert rules are assigned by default to each type of test to which they apply.

Field	Data Type	Units	Notes
ruleId	integer	n/a	unique ID of the alert rule
ruleName	string	n/a	name of the alert rule
notes	string	n/a	additional content sent to notification recipients in alert emails
expression	string	n/a	string expression of alert rule
notifyOnClear	boolean	n/a	1 to send notification when alert clears
roundsBeforeTrigger	integer	n/a	Valid options are 1-4; indicates the number of rounds where the criteria are met before triggering an alert
default	boolean	n/a	Alert rules allow up to 1 alert rule to be selected as a default for each type. By checking the default option, this alert rule will be automatically included on subsequently created tests that test a metric used in alerting here
recipient	array of email addresses	n/a	notification recipients are specified in an array of email addresses
alertType	string	n/a	type of alert rule, as determined by metric selection
minimumSources	integer	n/a	the minimum number of agents or monitors that must meet the specified criteria in order to trigger the alert

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "alertRules": [ { "ruleId": 322, "ruleName": "Default BGP Alert Rule", "notes": "", "expression": "((reachability < 100%))", "notifyOnClear": 0, "roundsBeforeTrigger": 1, "default": 1, "recipient": [], "alertType": "BGP" }, { "ruleId": 300, "ruleName": "Default DNS Server Alert Rule", "notes": "", "expression": "((probDetail != \"\"))", "minimumSources": 2, "notifyOnClear": 0, "roundsBeforeTrigger": 1, "default": 1, "recipient": [ "noreply@thousandeyes.com" ], "alertType": "DNS Server" } ] }

For error responses, see the response status codes documentation.

`GET /v5/alerts` Active Alerts

Returns a list of all active alerts, active at any given time.

Optional Parameters

format=json|xml optional, specifies the format of output requested. See Output Formats for more information
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={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

no request body

Example

$curl https://api.thousandeyes.com/v5/alerts.json \ -u {email}:{authToken}

Response

Sends back an array of active alerts, either at present, or based on the time range specified, indicating testId and testName, alert rule. If no alerts are active during the time range specified, an empty response will be returned.

Field	Data Type	Units	Notes
alertId	integer	n/a	unique ID of the alert; each alert occurrence is assigned a new unique ID
testId	integer	n/a	unique ID of the test (see `/tests/{testId}` endpoint for more detail)
ruleId	integer	n/a	unique ID of the alert rule (see `/alert-rules` endpoint for more detail)
testName	string	n/a	name of the test
active	integer	n/a	0 for inactive, 1 for active, 2 for disabled. Alert is disabled if either alert rule itself has been deleted or the test it is applied to has been disabled, deleted, disabled alerting, or disassociated the alert rule from the test
ruleExpression	string	n/a	string expression of alert rule
dateStart	dateTime	yyyy-MM-dd hh:mm:ss	the date/time where an alert rule was triggered
dateEnd	dateTime	yyyy-MM-dd hh:mm:ss	the date/time where the alert was marked as cleared
violationCount	integer	n/a	number of sources currently meeting the alert criteria
ruleName	string	n/a	name of the alert rule
permalink	string	n/a	permanent link to the test, with the starting round selected
type	string	n/a	type of alert being triggered
agents	array of agent objects	n/a	array of monitors where the alert has at some point been active since the point that the alert was triggered. Not shown on BGP alerts.
monitors	array of monitor objects	n/a	array of monitors where the alert has at some point been active since the point that the alert was triggered. Only shown on BGP alerts.
apiLinks	array of links	n/a	list of hyperlinks to other areas of the API

Agent and Monitor objects (see above) reflect the following content:

Field	Data Type	Units	Notes
dateStart	dateTime	yyyy-MM-dd hh:mm:ss	reflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold
dateEnd	dateTime	yyyy-MM-dd hh:mm:ss	reflects the earlier of the date that the alert was cleared, or the source reported a measurement that was under the alert rule’s threshold
active	integer	n/a	if the particular source is alerting when the API is queried, this flag will be set to 1. After an alert has cleared, this flag (regardless of the source’s metrics) will be set to 0, even if the particular source has not cleared the alert rule. If the rule has been subsequently disabled, the alert value will be set to 2.
metricsAtStart	string	n/a	string 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
metricsAtEnd	string	n/a	string 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.
agentId/monitorId	integer	n/a	unique ID of agent or monitor violating the alert rule. See `/agents` or `/bgp-monitors` for more detail
agentName/monitorName	string	n/a	display name of the agent or monitor violating the alert rule
permalink	string	n/a	hyperlink to alerts list, with row expanded

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "alert": [ { "alertId": 2783, "testId": 822, "ruleId": 142, "testName": "thousandeyes.com A", "active": 1, "ruleExpression": "Error details is not \"\"", "dateStart": "2012-12-13 13:15:00", "violationCount": 6, "ruleName": "Default DNSSEC Alert Rule", "createLinks": true, "permalink": "https://app.thousandeyes.com/alerts/list?__a=75&alertId=2783", "type": "DNSSEC", "agents": [ { "agentId": 12, "agentName": "Hong Kong", "dateStart": "2012-12-13 13:15:00", "active": 1, "metricsAtStart": "Error details: \"No DNSSEC public key(s) for thousandeyes.com A\"", "metricsAtEnd": "Error details: \"No DNSSEC public key(s) for thousandeyes.com A\"", "permalink": "https://app.thousandeyes.com/alerts/list?__a=75&alertId=2783&agentId=12" }, ... ], "apiLinks": [...] } ], "pages": { "current": 1 } }

For error responses, see the response status codes documentation.

`GET /v5/alerts/{alertId}` Alert Detail

Returns details about an alert.

Optional Parameters

format=json|xml optional, specifies the format of output requested. See Output Formats for more information
aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

no request body

Example

$curl https://api.thousandeyes.com/v5/alerts/34203.json \ -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.

Field	Data Type	Units	Notes
alertId	integer	n/a	unique ID of the alert; each alert occurrence is assigned a new unique ID
testId	integer	n/a	unique ID of the test (see `/tests/{testId}` endpoint for more detail)
ruleId	integer	n/a	unique ID of the alert rule (see `/alert-rules` endpoint for more detail)
testName	string	n/a	name of the test
active	integer	n/a	0 for inactive, 1 for active, 2 for disabled. Alert is disabled if either alert rule itself has been deleted or the test it is applied to has been disabled, deleted, disabled alerting, or disassociated the alert rule from the test
ruleExpression	string	n/a	string expression of alert rule
dateStart	dateTime	yyyy-MM-dd hh:mm:ss	the date/time where an alert rule was triggered
dateEnd	dateTime	yyyy-MM-dd hh:mm:ss	the date/time where the alert was marked as cleared
violationCount	integer	n/a	number of sources currently meeting the alert criteria
ruleName	string	n/a	name of the alert rule
permalink	string	n/a	hyperlink to alerts list, with row expanded
type	string	n/a	type of alert being triggered
agents	array of agent objects	n/a	array of monitors where the alert has at some point been active since the point that the alert was triggered. Not shown on BGP alerts.
monitors	array of monitor objects	n/a	array of monitors where the alert has at some point been active since the point that the alert was triggered. Only shown on BGP alerts.
apiLinks	array of links	n/a	list of hyperlinks to other areas of the API

Agent and Monitor objects (see above) reflect the following content:

Field	Data Type	Units	Notes
dateStart	dateTime	yyyy-MM-dd hh:mm:ss	reflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold
dateEnd	dateTime	yyyy-MM-dd hh:mm:ss	reflects the earlier of the date that the alert was cleared, or the source reported a measurement that was under the alert rule’s threshold
active	integer	n/a	if the particular source is alerting when the API is queried, this flag will be set to 1. After an alert has cleared, this flag (regardless of the source’s metrics) will be set to 0, even if the particular source has not cleared the alert rule. If the rule has been subsequently disabled, the alert value will be set to 2.
metricsAtStart	string	n/a	string 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
metricsAtEnd	string	n/a	string 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.
agentId/monitorId	integer	n/a	unique ID of agent or monitor violating the alert rule. See `/agents` or `/bgp-monitors` for more detail
agentName/monitorName	string	n/a	display name of the agent or monitor violating the alert rule
permalink	string	n/a	hyperlink to alerts list, with row expanded

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "alert": [ { "ruleId": 172, "alertId": 34203, "testId": 5176, "testName": "API created test", "active": 1, "ruleExpression": "Error type is not \"None\"", "dateStart": "2014-03-24 19:02:00", "violationCount": 2, "ruleName": "Default HTTP Alert Rule", "permalink": "https://app.thousandeyes.com/alerts/list?__a=11&alertId=34203", "type": "HTTP Server", "agents": [ { "dateStart": "2014-03-24 19:02:00", "active": 1, "metricsAtStart": "Error type: \"DNS\"", "metricsAtEnd": "Error type: \"DNS\"", "agentId": 107, "agentName": "Vancouver, Canada", "permalink": "https://app.thousandeyes.com/web/http-server?__a=11&testId=5176&roundId=1395699129&agentId=107" }, { "dateStart": "2014-03-24 19:01:48", "active": 1, "metricsAtStart": "Error type: \"DNS\"", "metricsAtEnd": "Error type: \"DNS\"", "agentId": 108, "agentName": "Boston, MA", "permalink": "https://app.thousandeyes.com/web/http-server?__a=11&testId=5176&roundId=1395699129&agentId=108" } ], "apiLinks": [...] } ] }

For error responses, see the response status codes documentation.

Your Privacy

Strictly Necessary Cookies

Performance Cookies

Targeting Cookies

Functional Cookies

DEVELOPER REFERENCE

Search Results

Overview

Tests

Test Data

Agents & Monitors

Alerts

Labels

User Management

Alerts

GET /v5/alert-rules Alert Rules

Optional Parameters

Request

Example

Response

Header

Body

GET /v5/alerts Active Alerts

Optional Parameters

Request

Example

Response

Header

Body

GET /v5/alerts/{alertId} Alert Detail

Optional Parameters

Request

Example

Response

Header

Body

`GET /v5/alert-rules` Alert Rules

`GET /v5/alerts` Active Alerts

`GET /v5/alerts/{alertId}` Alert Detail