Alerts & Notifications

GET /v6/alerts Active alerts

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

Optional (Querystring) 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={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/v6/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 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
ruleExpressionstringn/astring expression of alert rule
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 was marked as cleared, expressed in UTC
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, expressed in UTC
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
activebooleann/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.
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 Server: nginx Date: Mon, 09 May 2016 16:04:24 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: 1493373360 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

Body

{ "alert": [ { "alertId": 2783, "testId": 822, "ruleId": 142, "testName": "thousandeyes.com A", "active": 1, "ruleExpression": "((probDetail != \"\"))", "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 /v6/alerts/{alertId} Alert detail

Returns details about an alert.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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/v6/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
ruleIdintegern/aunique ID of the alert rule (see /alert-rules endpoint for more detail)
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)
testNamestringn/aname of the test
activeintegern/a0 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
ruleExpressionstringn/astring expression of alert rule
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 was marked as cleared, expressed in UTC
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 agents 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, expressed in UTC
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
activebooleann/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.
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 Server: nginx Date: Mon, 09 May 2016 16:04:24 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: 1493373360 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

Body

{ "alert": [ { "ruleId": 172, "alertId": 34203, "testId": 5176, "testName": "API created test", "active": 1, "ruleExpression": "((errorType != \"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=32403", "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.

GET /v6/alert-rules Alert rules

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

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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/v6/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
expressionstringn/astring expression of alert rule
directionstringn/aoptional field with one of the following values: TO_TARGET, FROM_TARGET, BIDIRECTIONAL, for applicable alert types (eg. path trace, End-to-End (Agent) etc.)
notifyOnClearbooleann/a1 to send notification when alert clears
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
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
minimumSourcesPctintegern/athe minimum percentage of all assigned agents or monitors that must meet the specified criteria in order to trigger the alert
roundsViolatingOutOfintegern/aapplies to only v6 and higher, specifies the divisor (y value) for the “X of Y times” condition.
roundsViolatingRequiredintegern/aapplies to only v6 and higher, specifies the numerator (x value) for the X of Y times” condition

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 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: 1493373360 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

Body

{ "alertRules": [ { "alertType": "Path Trace", "default": 0, "expression": "((hops((hopDelay >= 100 ms))))", "minimumSources": 1, "notifyOnClear": 1, "roundsViolatingOutOf": 10, "roundsViolatingRequired": 9, "ruleId": 99453, "ruleName": "The End of the Internet" }, { "alertType": "HTTP Server", "default": 0, "expression": "((errorType != \"None\"))", "minimumSourcesPct": 30, "notifyOnClear": 1, "roundsViolatingOutOf": 1, "roundsViolatingRequired": 1, "ruleId": 127094, "ruleName": "The End of the World" } ] }

For error responses, see the response status codes documentation.

GET /v6/alert-rules/{ruleId} Alert rule detail

Returns details about an alert rule.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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/v6/alert-rules/322.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

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

FieldData TypeUnitsNotes
ruleIdintegern/aunique ID of the alert rule
ruleNamestringn/aname of the alert rule
expressionstringn/astring expression of alert rule
directionstringn/aoptional field with one of the following values: TO_TARGET, FROM_TARGET, BIDIRECTIONAL, for applicable alert types (eg. path trace, End-to-End (Agent) etc.)
notificationsobject with notification propertiesn/aAlert notification object. See Alert notification integrations.
notifyOnClearbooleann/a1 to send notification when alert clears
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
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
minimumSourcesPctintegern/athe minimum percentage of all assigned agents or monitors that must meet the specified criteria in order to trigger the alert
roundsViolatingOutOfintegern/aapplies to only v6 and higher, specifies the divisor (y value) for the “X of Y times” condition.
roundsViolatingRequiredintegern/aapplies to only v6 and higher, specifies the numerator (x value) for the X of Y times” condition
testsarrayn/alist of tests alert rule is assigned to, expressed in the same format as /tests endpoint

If Alert Rule has email notifications configured, notifications object has an email parameter. Email object has the following parameters:

Field NameData TypeNotes
recipientarray of email addressesnotification recipients are specified in an array of email addresses
messagestringadditional content sent to notification recipients in alert emails

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 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: 1493373360 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

Body

{ "alertRules": [ { "ruleId": 322, "ruleName": "Default BGP Alert Rule", "notes": "", "expression": "((reachability < 100%))", "notifications": { "email": { "message": "", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "channel": "@primoz", "integrationId": "sl-57", "integrationName": "Slack to Primoz", "integrationType": "SLACK", "target": "https://hooks.slack.com/services/T0DXA4R8U/B2Y23HERL/uL3lz43raw1HfakeIDRChoOH" }, { "authMethod": "Auth Token", "authToken": "a2b93fakeToken39feacf5fea49defacdc", "authUser": "thousandeyes", "integrationId": 1234, "integrationName": "Frontend ThousandEyes", "integrationType": "PAGER_DUTY" } ] }, "notifyOnClear": 0, "roundsBeforeTrigger": 1, "default": 1, "recipient": [], "alertType": "BGP", "tests": [ { "alertsEnabled": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "contentRegex": "", "createdBy": "Primoz (noreply@thousandeyes.com)", "createdDate": "2016-12-14 19:18:51", "enabled": 1, "followRedirects": 1, "httpInterval": 120, "httpTargetTime": 1000, "httpTimeLimit": 5, "includeHeaders": 0, "interval": 300, "liveShare": 0, "modifiedBy": "Primoz (noreply@thousandeyes.com)", "modifiedDate": "2017-04-07 11:08:47", "mtuMeasurements": 0, "networkMeasurements": 1, "pageLoadTargetTime": 6, "pageLoadTimeLimit": 10, "savedEvent": 0, "sslVersion": "Auto", "sslVersionId": 0, "testId": 35180, "testName": "Google PL", "type": "page-load", "url": "http://google.com", "useNtlm": 0, "verifyCertificate": 1 } ] }, { "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.

Alert rule metadata

Alert rule fields are shown in the table below. The table indicates whether the fields can rule creation, updates, or simply in returning data. As a reminder, in order to create a new alert rule, the user attempting the creation must be in a role which includes the Edit Alert rules permission.

Fields are listed in the table below.

Where a field indicates n/a for both Alert rule creation and update, these fields are system-generated and read only, and displayed as part of test metadata.

FieldCreationUpdateData TypeAcceptsNotes/Example
alertTyperequiredrequiredstringAcceptable test types, verbose names.Page Load, HTTP Server, End-to-End (Server), End-to-End (Agent), Voice, DNS+ Domain, DNS+ Server, DNS Server, DNS Trace, DNSSEC, Web Transaction, BGP, Path Trace, FTP, SIP Server
ruleNamerequiredrequiredstringname of the alert ruleif an alert rule by this name already exists, the request will error
defaultoptionaloptionalbitto set the rule as a default, set this value to 1.Defaults to 0
expressionrequiredrequiredstringExpression string should be a valid JSON string.See examples in the table belowUse examples found on the Alert Rule Detail endpoint.
notificationsoptionaloptionalobject with notification propertiesSee notifications endpoint for examples"notifications": { "email": { "message": "NA", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "integrationId": "sl-101", "integrationType": "SLACK" }, {"integrationId": "pgd-21","integrationType": "PAGER_DUTY"} ], "webhook": [ { "integrationId": "wb-201", "integrationType": "WEBHOOK" } ] },
notifyOnClearoptionaloptionalbitset to 1 to trigger the notification when the alert clears.Defaults to 0.
testIdsoptionaloptionalarray of integersvalid test Ids"testIds": [12345, 12346]
minimumSourcesoptional*optional*integerThe minimum number of agents or monitors that must meet the specified criteria in order to trigger an alertEither minimumSources or minimumSourcesPct must be specified in create calls
minimumSourcesPctoptional*optional*integerThe minimum percentage of agents or monitors that must meet the specified criteria in order to trigger an alertEither minimumSources or minimumSourcesPct must be specified in create calls
roundsViolatingRequiredrequiredrequiredIntegerspecifies the divisor of the “X of Y times” condition in an alert rule.Minimum value is 1, maximum value is 10.
roundsViolatingOutOfrequiredrequiredIntegerspecifies the numerator of the “X of Y times” condition in an alert rule.Minimum value is 1, maximum value is 10.
directionoptionaloptionalstringFor alertTypes End-to-end (Agent) and Path Trace, field must be set to a value from this list: [TO_TARGET, FROM_TARGET, BIDIRECTIONAL]see accepts section
includeCoveredPrefixesoptionaloptionalbitset to 1 to include covered prefixes in the BGP alert rule. Only applicable to BGP alert rulesDefaults to 1

Expressions

The following table outlines a list of expressions that can be used when creating or modifying alert rules. Multiple metrics can be combined in a single rule with logical “and” and logical “or” operators, using double-ampersand (&&) and double-pipe (||), respectively. When combining three or more metrics, a single operator type is allowed, i.e. both logical “and” and logical “or” operators cannot be used. Note that not all metrics can be combined into a single rule.

For more information on metrics please refer to How alerts work for more information on supported metrics.

Alert typeMetricOperatorData typeExampleNotes
Internet InsightsASNinlist((asn in {2, 7, 8}))use autonomous system numbers
Internet Insights[all,any] domains[in, !in]list((all domains !in {"google.com", "facebook.com"}))domain names must be double-quote encapsulated
Internet Insights[all,any] locations[in, !in]list((all locations !in {1, 2}))not sure what to write here
Internet InsightsaffectedTestsCount[<, <=, ==, >=, >]Integer((affectedTestsCount >= 2))number of affected tests
Internet InsightsaffectedInterfacesCount[<, <=, ==, >=, >]Integer((affectedInterfacesCount >= 2))number of affected interfaces
Internet InsightsaffectedLocationsCount[<, <=, ==, >=, >]Integer((affectedLocationsCount >= 2))number of affected locations
HTTP ServerresponseCode[<, <=, ==, !=, >=, >]Integer((responseCode >= 400))HTTP response code returned by the test
HTTP ServerdnsTime[<, <=, ==, !=, >=, >]Integer + units((dnsTime >= 500 ms))ensure that you set units in the expression
HTTP ServerconnectTime[<, <=, ==, !=, >=, >]Integer + units((connectTime >= 500 ms))ensure that you set units in the expression
HTTP ServersslTime[<, <=, ==, !=, >=, >]Integer + units((sslTime >= 500 ms))ensure that you set units in the expression
HTTP ServerwaitTime[<, <=, ==, !=, >=, >]Integer + units((waitTime >= 500 ms))ensure that you set units in the expression
HTTP ServerreceiveTime[<, <=, ==, !=, >=, >]Integer + units((receiveTime >= 500 ms))ensure that you set units in the expression
HTTP ServertotalTime[<, <=, ==, !=, >=, >]Integer + units((totalTime >= 500 ms))ensure that you set units in the expression
HTTP ServerresponseTime[<, <=, ==, !=, >=, >]Integer + units((responseTime >= 500 ms))ensure that you set units in the expression
HTTP ServererrorType[=, !=][None, SSL, DNS, Connect]((errorType != "None"))errorType is specified as a string from list of valid error types. Double-quote enclose.
HTTP ServerclientSslAlertCode[==, !=]Integer((clientSslAlertCode != 40))SSL error code
HTTP ServerserverSslAlertCode[==, !=]Integer((serverSslAlertCode != 40))SSL error code
HTTP Serverthroughput[<, <=, ==, !=, >=, >]Integer + units((throughput >= 100 kbps))ensure that you set units in the expression.
HTTP ServerresponseHeaders[=~, !~]Regular expression((responseHeaders =~ /"\\wFoo\//))Text match for response headers
HTTP ServerprobDetail[=~, !=, !~]Regular expression((probDetail =~ /google/))Problem detail (???)
HTTP ServerredirectCount[<, <=, ==, !=, >=, >]Integer((redirectCount >= 2))Number of redirects from the target page
HTTP ServerwireSize[<, <=, ==, !=, >=, >]Float((wireSize > 1024.0 kB))ensure that you set units in the expression
FTP ServerftpReplyCode[<, <=, ==, !=, >=, >]Integer((ftpReplyCode >= 400))FTP reply code
FTP ServerdnsTime[<, <=, ==, !=, >=, >]Integer + units((dnsTime >= 500 ms))ensure that you set units in the expression
FTP ServerconnectTime[<, <=, ==, !=, >=, >]Integer + units((connectTime >= 500 ms))ensure that you set units in the expression
FTP ServersslTime[<, <=, ==, !=, >=, >]Integer + units((sslTime >= 500 ms))ensure that you set units in the expression
FTP ServernegotiationTime[<, <=, ==, !=, >=, >]Integer + units((negotiationTime >= 500 ms))ensure that you set units in the expression
FTP ServerwaitTime[<, <=, ==, !=, >=, >]Integer + units((waitTime >= 500 ms))ensure that you set units in the expression
FTP ServertransferTime[<, <=, ==, !=, >=, >]Integer + units((transferTime >= 500 ms))ensure that you set units in the expression
FTP ServertotalTime[<, <=, ==, !=, >=, >]Integer + units((totalTime >= 500 ms))ensure that you set units in the expression
FTP ServerresponseTime[<, <=, ==, !=, >=, >]Integer + units((responseTime >= 500 ms))ensure that you set units in the expression
FTP ServerftpErrorType[=, !=][None, SSL, DNS, Connect]((ftpErrorType != "None"))errorType is specified as a string from list of valid error types. Double-quote enclose.
FTP Serverthroughput[<, <=, ==, !=, >=, >]Integer + units((throughput >= 100 kbps))ensure that you set units in the expression.
Networkloss[<, <=, ==, !=, >=, >]Integer + %((loss >= 10%))set loss threshold in percent
NetworkavgLatency[<, <=, ==, !=, >=, >]Integer + units((avgLatency >= 100 ms))ensure that you set units in the expression
Networkjitter[<, <=, ==, !=, >=, >]Integer + units((jitter >= 15 ms))ensure that you set units in expression
NetworkavailBwCs[<, <=, ==, !=, >=, >]Integer + units((availBwCs >= 10 Mbps))ensure that you set units in expression
NetworkcapCs[<, <=, ==, !=, >=, >]Integer + units((capCs >= 10 Mbps))ensure that you set units in expression
AlllocationId[in, !in]list[(locationId !in {"1", "2"})]locationId reflects the agentId for agent-based tests, and monitorId for BGP-based tests
Page LoadpageLoadedn/an/a((!pageLoaded))use !pageLoaded to trigger an alert when the page doesn’t load
Page LoadpageLoadHasError[\==]boolean((pageLoadHasError == true))fire when the page load has a component error
Page LoadpageLoadTimedOut[==]boolean((pageLoadTimedOut == true))fire when page load times out
Page LoadtimeToFirstByte[<, <=, ==, !=, >=, >]Integer + units((timeToFirstByte >= 100 ms))ensure that you set units in the expression
Page LoadonContentLoadTime[<, <=, ==, !=, >=, >]Integer + units((onContentLoadTime >= 100 ms))ensure that you set units in the expression. This reflects the DOM Load value in the page load.
Page LoadonLoadTime[<, <=, ==, !=, >=, >]Integer + units((onLoadTime >= 100 ms))ensure that you set units in the expression. This metric reflects page load time.
Page LoaderrorCount[<, <=, ==, !=, >=, >]Integer((errorCount >= 2))number of component errors
Page Loadcomponentssee notessee notessee noteswrap component-specific criteria in a set of parentheses
Page Loaddomain[in, !in]list of strings((components((domain !in {"*.facebook.com"}))))must be wrapped by components(), applies at the component level
Page LoadtotalTime[<, <=, ==, !=, >=, >]Integer + units((components((totalTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoadblockedTime[<, <=, ==, !=, >=, >]Integer + units((components((totalTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoaddnsTime[<, <=, ==, !=, >=, >]Integer + units((components((dnsTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoadconnectTime[<, <=, ==, !=, >=, >]Integer + units((components((connectTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoadwaitTime[<, <=, ==, !=, >=, >]Integer + units((components((waitTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoadreceiveTime[<, <=, ==, !=, >=, >]Integer + units((components((receiveTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoadsslTime[<, <=, ==, !=, >=, >]Integer + units((components((sslTime >= 100 ms))))must be wrapped by components(), applies at the component level
Page LoadcomponentLoaded[==, !=]bit((components((componentLoaded == 0))))must be wrapped by components(), applies at the component level
Page LoadwireSize[<, <=, ==, !=, >=, >]float + units((wireSize > 1024.0 kB))ensure you set units as part of the expression
TransactionprobDetail[=~, !~]Regular expression((probDetail =~ /foo/))Problem details
Transactionduration[<, <=, ==, !=, >=, >]Integer + units((duration >= 100 ms))ensure you set units as part of the expression
Transactioncompletion[<, <=, ==, !=, >=, >]Integer + %((completion >= 98%))ensure you add the % symbol as part of the expression
TransactionstepsCompleted[<, <=, ==, !=, >=, >]Integer((stepsCompleted <= 3))Number of steps completed
Transactionstepssee notessee notessee noteswrap step-specific criteria in a set of parentheses, use array position to identify a specific step. Note that array is zero-based, so step 1 is steps[0]().
TransactionstepDuration[<, <=, ==, !=, >=, >]Integer + units((steps[1]((stepDuration >= 100 ms))))see note above re: use of steps[]
TransactionpagesCompleted[<, <=, ==, !=, >=, >]Integer((stepsCompleted <= 3))Number of pages completed
Transactionpagessee notessee notessee noteswrap page-specific criteria in a set of parentheses, use array position to identify a specific page. Note that array is zero-based, so page 1 is pages[0]().
TransactionpageDuration[<, <=, ==, !=, >=, >]Integer + units((pages[1]((pageDuration >= 100 ms))))see note above re: use of pages[]
DNS ServerprobDetail[=~, !=, !~]Regular expression((probDetail =~ /foo/))Problem details
DNS Serverdelay[<, <=, ==, !=, >=, >]Integer + units((delay >= 100 ms))ensure you set units as part of the expression
DNS ServermapData[in, !in]list((mapData !in {"10.0.0.0/8"}))list can reflect IP addresses, CIDR blocks, or strings. Wildcards are supported for domains
DNS TraceprobDetail[=~, !=, !~]Regular expression((probDetail =~ /foo/))Problem details
DNS TracemapData[in, !in]list((mapData !in {"10.0.0.0/8"}))list can reflect IP addresses, CIDR blocks, or strings. Wildcards are supported for domains
DNSSECprobDetail[=~, !=, !~]Regular expression((probDetail =~ /foo/))Problem details
Voicemos[<, <=, ==, !=, >=, >]Float((mos >= 2.75))note: mean opinion scores do not have units
Voiceloss[<, <=, ==, !=, >=, >]Integer + %((loss >= 10%))set loss threshold in percent
Voicelatency[<, <=, ==, !=, >=, >]Integer + units((latency >= 100 ms))ensure that you set units in the expression
Voicepdv[<, <=, ==, !=, >=, >]Integer + units((pdv >= 15 ms))ensure that you set units in expression
Voiceloss[<, <=, ==, !=, >=, >]Integer + %((loss >= 10%))set loss threshold in percent
Voicediscards[<, <=, ==, !=, >=, >]Integer + %((discards >= 10%))set discard threshold in percent
Voicedscp[==, !=]Integer((dscp != 26))set DSCP value received by target agent
VoiceprobDetail[=~, !=, !~]Regular expression((probDetail =~ /foo/))Problem details
SIP ServersipResponseCode[<, <=, ==, !=, >=, >]Integer((sipResponseCode >= 400))reflects response code to SIP register
SIP ServersipErrorType[==, !=]string((sipErrorType != "None"))SIP error type (dns, connect, register, invite, options, none)
SIP ServerdnsTime[<, <=, ==, !=, >=, >]Integer + units((dnsTime >= 100 ms))ensure you set units as part of the expression
SIP ServerconnectTime[<, <=, ==, !=, >=, >]Integer + units((connectTime >= 100 ms))ensure you set units as part of the expression
SIP ServerregisterTime[<, <=, ==, !=, >=, >]Integer + units((registerTime >= 100 ms))ensure you set units as part of the expression
SIP ServerinviteTime[<, <=, ==, !=, >=, >]Integer + units((inviteTime >= 100 ms))ensure you set units as part of the expression
SIP ServeroptionsTime[<, <=, ==, !=, >=, >]Integer + units((optionsTime >= 100 ms))ensure you set units as part of the expression
SIP ServerwaitTime[<, <=, ==, !=, >=, >]Integer + units((waitTime >= 100 ms))ensure you set units as part of the expression
SIP ServerresponseTime[<, <=, ==, !=, >=, >]Integer + units((responseTime >= 100 ms))ensure you set units as part of the expression
SIP ServertotalTime[<, <=, ==, !=, >=, >]Integer + units((totalTime >= 100 ms))ensure you set units as part of the expression
Agent to Agentloss[<, <=, ==, !=, >=, >]Integer + %((loss >= 10%))set loss threshold in percent
Agent to Agentlatency[<, <=, ==, !=, >=, >]Integer + units((latency >= 100 ms))ensure that you set units in the expression
Agent to Agentjitter[<, <=, ==, !=, >=, >]Integer + units((jitter >= 15 ms))ensure that you set units in expression
Agent to Agentthroughput[<, <=, ==, !=, >=, >]Integer + units((throughput >= 10 Mbps))ensure that you set units in expression
Agent to AgentprobDetail[=~, !=, !~]Regular expression((probDetail =~ /foo/))Problem detail
Agent to Agentdscp[==, !=]Integer((dscp != 26))set DSCP value received by target agent
Agent to AgentbothWaysLoss[<, <=, ==, !=, >=, >]Integer + %((bothWaysLoss >= 10%))set loss threshold in percent
Agent to AgentbothWaysLatency[<, <=, ==, !=, >=, >]Integer + units((bothWaysLatency >= 100 ms))ensure that you set units in the expression
Agent to AgentbothWaysJitter[<, <=, ==, !=, >=, >]Integer + units((bothWaysJitter >= 15 ms))ensure that you set units in expression
Agent to AgentbothWaysThroughput[<, <=, ==, !=, >=, >]Integer + units((bothWaysThroughput >= 10 Mbps))ensure that you set units in expression
Agent to AgentbothWaysProbDetail[=~, !=, !~]Regular expression((probDetail =~ /foo/))Problem details
Path TraceserverIP[in, !in]list((serverIp !in {"20.0.0.1", "10.0.0.0/8"}))IP address of target server
Path Tracemss[<, <=, ==, !=, >=, >]Integer + units((mss >= 1460 B))ensure you set units as part of the expression
Path TracepathMtu[<, <=, ==, !=, >=, >]Integer + units((pathMtu >= 1500 B))ensure you set units as part of the expression
Path TracepathLength[<, <=, ==, !=, >=, >]Integer((pathLength >= 15))total length of the path from source to target
Path TraceisTerminal[==]Boolean((isTerminal == true))Value is set to true in the event that the path trace does not reach the destination
Path Tracehopssee notessee notessee noteswrap hop-specific criteria in a set of parentheses, use array position to indicate hop number. To test any hop, use hops without specifying an array. Use negative numbers to test hops from target.
Path TracenoHopssee notessee notessee noteswrap hop-specific criteria in a set of parentheses, use array position to indicate hop number. No hops indicates the opposite of hops().
Path Tracempls[==]null((hops((mpls != null))))use in conjunction with hops() or nohops()
Path Tracedscp[==, !=]Integer((dscp != 26))set DSCP value received by target agent. use in conjunction with hops() or nohops()
Path Traceip[in, !in]list((hops[-1]((ip !in {"20.0.0.1", "10.0.0.0/8"}))))use in conjunction with hops() or nohops(). example shows last hop before destination.
Path Traceasn[in, !in]list((hops((asn !in {1111, 65536}))))use in conjunction with hops() or nohops().
Path Tracerdns[in, !in]list((hops((rdns !in {"*.facebook.com", "*.google.com"}))))use in conjunction with hops() or nohops().
BGPreachability[<, <=, ==, !=, >=, >]Integer + %((reachability <= 90%))ensure you set percentage as part of the expression
BGPchanges[<, <=, ==, !=, >=, >]Float((changes >= 1.1))ensure you set percentage as part of the expression
BGPprefixLengthIPv4[<, <=, ==, !=, >=, >]Integer((prefixLengthIPv4 >= 23))typically used in compound statements where covered prefixes are monitored
BGPprefixLengthIPv6[<, <=, ==, !=, >=, >]Integer((prefixLengthIPv4 >= 47))typically used in compound statements where covered prefixes are monitored
BGPprefix[in, !in]list((prefix !in {"10.0.0.0/18"}))typically used in compound statements where covered prefixes are monitored
BGPsubprefix[in, !in]list((subprefix !in {"10.1.0.0/24"}))typically used in compound statements where covered prefixes are monitored
BGPbgpHopssee notessee notessee notesan array representing AS Path for BGP monitors. Use array index to identify hops from origin, use negative array index to identify hops from monitor, or no index to represent the entire array.
BGPnoBgpHopssee notessee notessee notesan array representing AS Path for BGP monitors. Use array index to identify hops from origin, use negative array index to identify hops from monitor, or no index to represent the entire array.
BGPasn[in, !in]list((bgpHops[1]((asn in {6}))))use in conjunction with bgpHops() or noBgpHops()

POST /v6/alert-rules/new Creating an alert rule

Creates a new alert rule in your account, based on properties provided in the POST data. In order to create a new alert rule, the user attempting the creation must be in a role that has the Edit alert rules permission. Users without this permission will receive an error.

Note: when assigning any alert rule to a test (which can be done as part of the creation activity), the user must be in a role that has the Edit tests permission.

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

  • request body must contain fields to be set during creation. See the Alert Rule Metadata page for fields available during alert rule creation.

Example

Please note, object creation/modification/deletion is not allowed on the Sandbox API account, and will not work if attempted. The following example is presented for documentation and reference purposes only.

$ curl https://api.thousandeyes.com/v6/alert-rules/new \ -H 'Content-Type: application/json' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 \ -d '{ "alertType": "FTP", "default": 0, "expression": "((reachability < 90%))", "minimumSources": 10, "notes": "FTP Alert rule created using write api", "description": "TE FTP Alert rule with write api", "notifications": { "email": { "message": "", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "integrationId": "sl-101", "integrationType": "SLACK" } ], "webhook": [ { "integrationId": "wb-201", "integrationType": "WEBHOOK" } ] }, "notifyOnClear": 1, "roundsViolatingOutOf": 10, "roundsViolatingRequired": 10, "ruleName": "FTP Alert Rule", "sourceMeasure": "percent", "testIds": [ 1001, 1002 ] }'

Response

If successful, will respond with an HTTP/201 response and a body which contains the new alert rule definition.

HTTP/1.1 201 CREATED HTTP/1.1 201 CREATED Server: nginx Date: Mon, 01 August 2019 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "alertRuleId": 2111, "alertType": "FTP", "default": 0, "expression": "((reachability < 90%))", "minimumSources": 10, "notes": "FTP Alert rule created using write api", "description": "TE FTP Alert rule with write api", "notifications": { "email": { "message": "", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "integrationId": "sl-101", "integrationType": "SLACK" } ], "webhook": [ { "integrationId": "wb-201", "integrationType": "WEBHOOK" } ] }, "notifyOnClear": 1, "roundsViolatingOutOf": 10, "roundsViolatingRequired": 10, "ruleName": "FTP Alert Rule", "sourceMeasure": "percent", "testIds": [ 1001, 1002 ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/alert-rules/{ruleId}/update Updating an alert rule

Modifies an existing alert rule in your account, based on properties provided in the POST data. In order to modify an alert rule, the user attempting the creation must be in a role that has the Edit alert rules permission. Users without this permission will receive an error.

Note: when assigning any alert rule to a test (which can be done as part of the update activity), the user must be in a role that has the Edit tests permission.

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

  • {ruleId} corresponds to a ruleId returned by the /alert-rules endpoint.
  • request body must contain a full list of fields. It is recommended to make a request to the alert-rules/{ruleId} endpoint and modify the conditions of the alert rule based on fields returned in that request. See the Alert Rule Metadata page for fields available during alert rule modification.

Example

Please note, object creation/modification/deletion is not allowed on the Sandbox API account, and will not work if attempted. The following example is presented for documentation and reference purposes only.

$ curl https://api.thousandeyes.com/v6/alert-rules/123/update \ -H 'Content-Type: application/json' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 \ -d '{ "alertType": "FTP", "default": 0, "expression": "((reachability < 90%))", "minimumSources": 10, "notes": "FTP Alert rule created using write api", "description": "TE FTP Alert rule with write api", "notifications": { "email": { "message": "", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "integrationId": "sl-101", "integrationType": "SLACK" } ], "webhook": [ { "integrationId": "wb-201", "integrationType": "WEBHOOK" } ] }, "notifyOnClear": 1, "roundsViolatingOutOf": 10, "roundsViolatingRequired": 10, "ruleName": "FTP Alert Rule", "sourceMeasure": "percent", "testIds": [ 1001, 1002 ] }'

Response

If successful, will respond with an HTTP/200 response and the modified rule definition in the body.

HTTP/1.1 200 CREATED Date: Fri, 12 Jul 2019 22:06:04 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Server-Name: ldkvx Cache-Control: no-store X-Organization-Rate-Limit-Limit: 600 X-Organization-Rate-Limit-Remaining: 599 X-Organization-Rate-Limit-Reset: 1562969220 Strict-Transport-Security: max-age=15724800; includeSubDomains Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff

Body

{ "alertRuleId": 1234, "alertType": "FTP", "default": 0, "expression": "((reachability < 90%))", "minimumSources": 10, "notes": "FTP Alert rule created using write api", "description": "TE FTP Alert rule with write api", "notifications": { "email": { "message": "", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "integrationId": "sl-101", "integrationType": "SLACK" } ], "webhook": [ { "integrationId": "wb-201", "integrationType": "WEBHOOK" } ] }, "notifyOnClear": 1, "roundsViolatingOutOf": 10, "roundsViolatingRequired": 10, "ruleName": "FTP Alert Rule", "sourceMeasure": "percent", "testIds": [ 1001, 1002 ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/alert-rules/{ruleId}/delete Deleting an alert rule

Deletes an alert rule in your account. In order to delete an alert rule, the user attempting the creation must be in a role that has the Edit alert rules permission, as well as Edit Tests permission, in the event that the alert rule is assigned to any tests. Users without appropriate permissions will receive an error.

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

  • {ruleId} corresponds to a ruleId returned by the /alert-rules endpoint.

Example

$ curl https://api.thousandeyes.com/v6/alert-rules/1234/delete \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Response header will be returned as HTTP/204 response code. No response body will be returned.

HTTP/1.1 204 No Content Date: Fri, 12 Jul 2019 22:11:49 GMT Connection: keep-alive X-Server-Name: 9gxxn Cache-Control: no-store X-Organization-Rate-Limit-Limit: 600 X-Organization-Rate-Limit-Remaining: 599 X-Organization-Rate-Limit-Reset: 1562969520 Strict-Transport-Security: max-age=15724800; includeSubDomains Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff

Body

For error responses, see the response status codes documentation.

GET /v6/integrations Alert notification integrations

Returns a list of all alert notification integrations (webhooks, PagerDuty, Slack, HipChat, …)

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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/v6/integrations.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Returns an object with two array properties: thirdParty and webhook.

thirdParty array objects reflect the following content:

FieldData TypeUnitsNotes
integrationIdintegern/aunique ID of the integration
integrationNamestringn/aname of the integration
integrationTypestringn/atype of the integration, PAGER_DUTY, HIPCHAT or SLACK
targetstringn/atarget URL of the integration
authMethodstringn/a(PagerDuty & HipChat only) always set to Auth Token
authUserstringn/a(PagerDuty only) PagerDuty user
authTokenstringn/a(PagerDuty & HipChat only HipChat authentication token
channelstringn/a(Slack only) Slack #channel or @user

webhook array objects reflect the following content:

FieldData TypeUnitsNotes
integrationIdintegern/aunique ID of the integration
integrationNamestringn/aname of the integration
integrationTypestringn/atype of the integration, always set to WEBHOOK
targetstringn/atarget URL of the integration

Body

{ "integrations": { "thirdParty": [ { "authMethod": "Auth Token", "authToken": "0a4693462246893f9393ed8ab2bf22f69", "authUser": "te", "integrationId": 123, "integrationName": "Jira Thousandeyes", "integrationType": "PAGER_DUTY" }, { "authMethod": "Auth Token", "integrationId": "hc-12", "integrationName": "HipChat integraspiel", "integrationType": "HIPCHAT", "target": "Hello" }, { "channel": "@primoz", "integrationId": 789, "integrationName": "ThousandEyes Private", "integrationType": "SLACK", "target": "https://hooks.slack.com/services/T3G3DA1EY/B3243AG4Q/kwGHQz126speipc3E0e0Hx" } ], "webhook": [ { "integrationId": 999, "integrationName": "Alert ThousandEyes", "integrationType": "WEBHOOK", "target": "https://webhooker.example.com/alert/z126g4a3f2a" } ] } }

For error responses, see the response status codes documentation.

GET /v6/alert-suppression-windows Alert suppression windows

Returns a list of all alert suppression windows configured in your account group.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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/v6/alert-suppression-windows.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Returns an alert suppression window object.

FieldData TypeUnitsNotes
alertSuppressionWindowIdintegern/aunique ID of the alert suppression window
alertSuppressionWindowNamestringn/aname of the alert suppression window
enabledbitn/a0 for disabled, 1 for enabled
statusstringn/a[ACTIVE, INACTIVE, ENDED], indicates the current status of the suppression window
startDateTimedateTimeyyyy-MM-dd hh:mm:ssthe date/time when the alert suppression window will start.
timezonestringn/atimezone name, in Area/Location format, as specified in the IANA TZDB.
durationintegersecondsnumber of minutes for which the suppression window will be active
repeatrepeat objectn/asee repeat options found below
repeat.typestringn/a[DAY, WEEK, MONTH, CUSTOM]
repeat.intervalTypestringn/a[DAY, WEEK, MONTH]
repeat.intervalLengthintegern/anumber of intervalTypes to wait before reactivating the alert suppression window.
repeat.daysOfWeekstringn/aSpecify which day of the week the alert suppression window needs to be activated for. Only valid for intervalType = WEEK. [SUN, MON, TUE, WED, THU, FRI, SAT]
endRepeatrepeat objectn/asee endRepeat options found below
endRepeat.typestringn/a[COUNT, NEVER, DATE]
endRepeat.countintegern/aend repeat after number of occurrences (only valid with COUNT type option)
endRepeat.datedateyyyy-MM-ddend repeat after specific date (only valid with DATE type option)

Body

{ "alertSuppressionWindows": [ { "alertSuppressionWindowId": 2411, "alertSuppressionWindowName": "Monthly maintenance", "duration": 300, "enabled": 0, "endRepeat": { "type": "NEVER" }, "repeat": { "type": "MONTH" }, "startDateTime": "2017-07-01 05:00:00", "status": "INACTIVE", "timezone": "UTC" } ] }

For error responses, see the response status codes documentation.

GET /v6/alert-suppression-windows/{alertSuppressionWindowId} Alert suppression window detail

Returns details for an alert suppression window configured in your account group.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

  • {alertSuppressionWindowId} corresponds to the id of an alertSuppressionWindow, see the alert suppression window list endpoint for a listing of alert suppression windows.
  • No request body

Example

$ curl https://api.thousandeyes.com/v6/alert-suppression-windows/2411.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Returns an alert suppression window object’s details, along with configured tests.

FieldData TypeUnitsNotes
alertSuppressionWindowIdintegern/aunique ID of the alert suppression window
alertSuppressionWindowNamestringn/aname of the alert suppression window
enabledbitn/a0 for disabled, 1 for enabled
statusstringn/a[ACTIVE, INACTIVE, ENDED], indicates the current status of the suppression window
testsarray of {“testId”: testId} objectsn/aList of tests assigned to the alert suppression window: [{“testId”: 123}, {“testId”: 456}]
startDateTimedateTimeyyyy-MM-dd hh:mm:ssthe date/time when the alert suppression window will start.
timezonestringn/atimezone name, in Area/Location format, as specified in the IANA TZDB.
durationintegersecondsnumber of minutes for which the suppression window will be active
repeatrepeat objectn/asee repeat options found below
repeat.typestringn/a[DAY, WEEK, MONTH, CUSTOM]
repeat.intervalTypestringn/a[DAY, WEEK, MONTH]
repeat.intervalLengthintegern/anumber of intervalTypes to wait before reactivating the alert suppression window.
repeat.daysOfWeekstringn/aSpecify which day of the week the alert suppression window needs to be activated for. Only valid for intervalType = WEEK. [SUN, MON, TUE, WED, THU, FRI, SAT]
endRepeatrepeat objectn/asee endRepeat options found below
endRepeat.typestringn/a[COUNT, NEVER, DATE]
endRepeat.countintegern/aend repeat after number of occurrences (only valid with COUNT type option)
endRepeat.datedateyyyy-MM-ddend repeat after specific date (only valid with DATE type option)

Body

{ "alertSuppressionWindows": [ { "alertSuppressionWindowId": 2411, "alertSuppressionWindowName": "Monthly maintenance", "duration": 300, "enabled": 0, "endRepeat": { "type": "NEVER" }, "repeat": { "type": "MONTH" }, "startDateTime": "2017-07-01 05:00:00", "status": "INACTIVE", "tests": [ { "alertsEnabled": 1, "apiLinks": [...], "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 20:44:05", "domain": "thousandeyes.com ANY", "enabled": 1, "interval": 900, "liveShare": 0, "modifiedBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "modifiedDate": "2017-06-19 18:53:39", "savedEvent": 0, "testId": 820, "testName": "thousandeyes.com ANY", "type": "dns-trace" }, ... ], "timezone": "UTC" } ] }

For error responses, see the response status codes documentation.

POST /v6/alert-suppression-windows/new Creating an alert suppression window

Creates a new alert suppression window in ThousandEyes, based on properties provided in the POST data. In order to create a new alert suppression window, the user attempting the creation must be an Account Admin.

Regular users are blocked from using any of the POST-based methods.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

  • request body containing the following fields:
FieldData TypeUnitsNotes
alertSuppressionWindowNamestringn/aname of the alert suppression window
enabledbitn/a0 for disabled, 1 for enabled
testsarray of {“testId”: testId} objectsn/aList of tests assigned to the alert suppression window: [{“testId”: 123}, {“testId”: 456}]
startDateTimedateTimeyyyy-MM-dd hh:mm:ssthe date/time when the alert suppression window will start.
timezonestringn/atimezone name, in Area/Location format, as specified in the IANA TZDB.
durationintegersecondsnumber of minutes for which the suppression window will be active
repeatrepeat objectn/asee repeat options found below
repeat.typestringn/a[DAY, WEEK, MONTH, CUSTOM]
repeat.intervalTypestringn/a[DAY, WEEK, MONTH]
repeat.intervalLengthintegern/anumber of intervalTypes to wait before reactivating the alert suppression window.
repeat.daysOfWeekstringn/aSpecify which day of the week the alert suppression window needs to be activated for. Only valid for intervalType = WEEK. [SUN, MON, TUE, WED, THU, FRI, SAT]
endRepeatrepeat objectn/asee endRepeat options found below
endRepeat.typestringn/a[COUNT, NEVER, DATE]
endRepeat.countintegern/aend repeat after number of occurrences (only valid with COUNT type option)
endRepeat.datedateyyyy-MM-ddend repeat after specific date (only valid with DATE type option)

Example

$ curl https://api.thousandeyes.com/v6/alert-suppression-windows/new.json \ -d '{ "alertSuppressionWindowName": "30 min asw created asw via API", "enabled": 1, "startDateTime": "2017-03-15 00:00:00", "timezone": "America/Los_Angeles", "duration": 1800, "repeat": { "type": "DAY" }, "endRepeat": { "type": "NEVER" } }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If an alert suppression window is successfully created, an HTTP/201 CREATED response will be returned, and the alert suppression window detail will be returned. See the example below:

Body

{ "alertSuppressionWindows": [ { "alertSuppressionWindowId": 230, "alertSuppressionWindowName": "30 min asw created asw via API", "enabled": 1, "status": "INACTIVE", "tests": [], "startDateTime": "2017-03-15 07:00:00", "timezone": "America/Los_Angeles", "duration": 1800, "repeat": { "type": "DAY" }, "endRepeat": { "type": "NEVER" } } ] }

For error responses, see the response status codes documentation.

POST /v6/alert-suppression-windows/{alertSuppressionWindowId}/update Updating an alert suppression window

Updates an alert suppression window in ThousandEyes, based on properties provided in the POST data. In order to modify an alert suppression window, the user attempting the update must be an Account Admin.

Regular users are blocked from using any of the POST-based methods.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

  • {alertSuppressionWindowId} corresponds to the id of an alertSuppressionWindow, see the alert suppression window list endpoint for a listing of alert suppression windows.
  • Request body containing the following fields
FieldData TypeUnitsNotes
alertSuppressionWindowNamestringn/aname of the alert suppression window
enabledbitn/a0 for disabled, 1 for enabled
testsarray of {“testId”: testId} objectsn/aList of tests assigned to the alert suppression window: [{“testId”: 123}, {“testId”: 456}]
startDateTimedateTimeyyyy-MM-dd hh:mm:ssthe date/time when the alert suppression window will start.
timezonestringn/atimezone name, in Area/Location format, as specified in the IANA TZDB.
durationintegersecondsnumber of minutes for which the suppression window will be active
repeatrepeat objectn/asee repeat options found below
repeat.typestringn/a[DAY, WEEK, MONTH, CUSTOM]
repeat.intervalTypestringn/a[DAY, WEEK, MONTH]
repeat.intervalLengthintegern/anumber of intervalTypes to wait before reactivating the alert suppression window.
repeat.daysOfWeekstringn/aSpecify which day of the week the alert suppression window needs to be activated for. Only valid for intervalType = WEEK. [SUN, MON, TUE, WED, THU, FRI, SAT]
endRepeatrepeat objectn/asee endRepeat options found below
endRepeat.typestringn/a[COUNT, NEVER, DATE]
endRepeat.countintegern/aend repeat after number of occurrences (only valid with COUNT type option)
endRepeat.datedateyyyy-MM-ddend repeat after specific date (only valid with DATE type option)

Example

$ curl https://api.thousandeyes.com/v6/alert-suppression-windows/230/update.json \ -d '{ "alertSuppressionWindowName": "30 min asw created asw via API -- modified to be 60 mins", "enabled": 1, "startDateTime": "2017-03-15 00:00:00", "timezone": "America/Los_Angeles", "duration": 3600, "repeat": { "type": "DAY" }, "endRepeat": { "type": "NEVER" } }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If an alert suppression window is successfully created, an HTTP/200 OK response will be returned, and the alert suppression window detail will be returned. See the example below:

Body

{ "alertSuppressionWindows": [ { "alertSuppressionWindowId": 230, "alertSuppressionWindowName": "30 min asw created asw via API -- modified to be 60 mins", "enabled": 1, "status": "INACTIVE", "tests": [], "startDateTime": "2017-03-15 07:00:00", "timezone": "America/Los_Angeles", "duration": 3600, "repeat": { "type": "DAY" }, "endRepeat": { "type": "NEVER" } } ] }

For error responses, see the response status codes documentation.

POST /v6/alert-suppression-windows/{alertSuppressionWindowId}/delete Deleting an alert suppression window

Deletes an alert suppression window.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

  • {alertSuppressionWindowId} corresponds to the id of an alertSuppressionWindow, see the alert suppression window list endpoint for a listing of alert suppression windows.
  • No request body

Example

$ curl https://api.thousandeyes.com/v6/alert-suppression-windows/217/delete.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 -H "Content-Type: application/json"

Response

If an alert suppression window is successfully deleted, an HTTP/204 NO CONTENT response will be returned, and an empty JSON response will be in the body of the response.

HTTP/1.1 204 NO CONTENT Server: nginx Date: Mon, 09 May 2016 16:04:24 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: 1493373360 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

Body

  • The body of a delete request will be empty.

For error responses, see the response status codes documentation.