Alerts & Notifications

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
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
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": "Any Hop: (Delay \u2265 100,000 ms)", "notifyOnClear": 1, "roundsViolatingOutOf": 10, "roundsViolatingRequired": 9, "ruleId": 99453, "ruleName": "The End of the Internet" }, { "alertType": "HTTP Server", "default": 0, "expression": "Error Type is any", "minimumSources": 1, "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
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
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.

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": "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 /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": "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=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/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.