Alerts

GET /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/alert-rules.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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.

FieldData TypeUnitsNotes
ruleIdintegern/aunique ID of the alert rule
ruleNamestringn/aname of the alert rule
notesstringn/aadditional content sent to notification recipients in alert emails
expressionstringn/astring expression of alert rule
notifyOnClearbooleann/a1 to send notification when alert clears
roundsBeforeTriggerintegern/aValid options are 1-4; indicates the number of rounds where the criteria are met before triggering an alert
defaultbooleann/aAlert 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
recipientarray of email addressesn/anotification recipients are specified in an array of email addresses
alertTypestringn/atype of alert rule, as determined by metric selection
minimumSourcesintegern/athe 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 /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/alerts.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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.

FieldData TypeUnitsNotes
alertIdintegern/aunique ID of the alert; each alert occurrence is assigned a new unique ID
testIdintegern/aunique ID of the test (see /tests/{testId} endpoint for more detail)
ruleIdintegern/aunique ID of the alert rule (see /alert-rules endpoint for more detail)
testNamestringn/aname of the test
activeintegern/a0 for inactive, 1 for active, 2 for disabled. Alert is disabled if either alert itself is disabled or the test it is applied to is disabled.
ruleExpressionstringn/astring expression of alert rule
dateStartdateTimeyyyy-MM-dd hh:mm:ssthe date/time where an alert rule was triggered
dateEnddateTimeyyyy-MM-dd hh:mm:ssthe date/time where the alert was marked as cleared
violationCountintegern/anumber of sources currently meeting the alert criteria
ruleNamestringn/aname of the alert rule
permalinkstringn/apermanent link to the test, with the starting round selected
typestringn/atype of alert being triggered
agentsarray of agent objectsn/aarray of monitors where the alert has at some point been active since the point that the alert was triggered. Not shown on BGP alerts.
monitorsarray 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.
apiLinksarray of linksn/alist of hyperlinks to other areas of the API

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

FieldData TypeUnitsNotes
dateStartdateTimeyyyy-MM-dd hh:mm:ssreflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold
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
activeintegern/aif 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.
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
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.
agentId/monitorIdintegern/aunique ID of agent or monitor violating the alert rule. See /agents or /bgp-monitors for more detail
agentName/monitorNamestringn/adisplay name of the agent or monitor violating the alert rule
permalinkstringn/ahyperlink 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 /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/alerts/34203.json \ -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.

FieldData TypeUnitsNotes
alertIdintegern/aunique ID of the alert; each alert occurrence is assigned a new unique ID
testIdintegern/aunique ID of the test (see /tests/{testId} endpoint for more detail)
ruleIdintegern/aunique ID of the alert rule (see /alert-rules endpoint for more detail)
testNamestringn/aname of the test
activeintegern/a0 for inactive, 1 for active, 2 for disabled. Alert is disabled if either alert itself is disabled or the test it is applied to is disabled.
ruleExpressionstringn/astring expression of alert rule
dateStartdateTimeyyyy-MM-dd hh:mm:ssthe date/time where an alert rule was triggered
dateEnddateTimeyyyy-MM-dd hh:mm:ssthe date/time where the alert was marked as cleared
violationCountintegern/anumber of sources currently meeting the alert criteria
ruleNamestringn/aname of the alert rule
permalinkstringn/ahyperlink to alerts list, with row expanded
typestringn/atype of alert being triggered
agentsarray of agent objectsn/aarray of monitors where the alert has at some point been active since the point that the alert was triggered. Not shown on BGP alerts.
monitorsarray 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.
apiLinksarray of linksn/alist of hyperlinks to other areas of the API

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

FieldData TypeUnitsNotes
dateStartdateTimeyyyy-MM-dd hh:mm:ssreflects the date that the source began reporting a measurement that exceeded the alert rule’s threshold
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
activeintegern/aif 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.
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
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.
agentId/monitorIdintegern/aunique ID of agent or monitor violating the alert rule. See /agents or /bgp-monitors for more detail
agentName/monitorNamestringn/adisplay name of the agent or monitor violating the alert rule
permalinkstringn/ahyperlink 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.