Synthetic monitors API - PUT a monitor

Updates the specified monitor.

The configuration of the monitor is passed via its JSON script.

You can copy the script of an existing monitor and adjust it as needed.

PUT	Managed	`https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/monitors/{monitorId}`
	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/monitors/{monitorId}`
	Environment ActiveGate	`https://{your-activegate-domain}/e/{your-environment-id}/api/v1/synthetic/monitors/{monitorId}`

Authentication

To execute this request, you need an access token with Create and read synthetic monitors, locations, and nodes (ExternalSyntheticIntegration) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

To find all model variations that depend on the type of the model, see JSON models.

Parameter	Type	Description	In	Required
monitorId	string	The ID of the synthetic monitor to be updated.	path	required
body	SyntheticMonitorUpdate	The synthetic monitor update. The actual set of fields depends the type of the monitor. Find the list of actual objects in the description of the type field or see Synthetic monitors API - JSON models.	body	optional

Parameter

Type

Description

Required

monitorId

string

The ID of the synthetic monitor to be updated.

path

required

body

SyntheticMonitorUpdate

The synthetic monitor update.

The actual set of fields depends the type of the monitor. Find the list of actual objects in the description of the type field or see Synthetic monitors API - JSON models.

body

optional

Request body objects

The `SyntheticMonitorUpdate` object

The synthetic monitor update.

The actual set of fields depends the type of the monitor. Find the list of actual objects in the description of the type field or see Synthetic monitors API - JSON models.

Element	Type	Description
frequencyMin	integer	The frequency of the monitor, in minutes. You can use one of the following values: `5`, `10`, `15`, `30`, and `60`.
anomalyDetection	AnomalyDetection	The anomaly detection configuration. Can be `null`.
type	string	Defines the actual set of fields depending on the value. See one of the following objects: `BROWSER` -> BrowserSyntheticMonitorUpdate `HTTP` -> HttpSyntheticMonitorUpdate The element can hold these values `BROWSER` `HTTP`
name	string	The name of the monitor.
locations	string[]	A list of locations from which the monitor is executed. To specify a location, use its entity ID.
enabled	boolean	The monitor is enabled (`true`) or disabled (`false`).
script	object	The script of a browser or HTTP monitor.
tags	TagWithSourceInfo[]	A set of tags assigned to the monitor. You can specify only the value of the tag here and the `CONTEXTLESS` context and source 'USER' will be added automatically. But preferred option is usage of TagWithSourceDto model.
manuallyAssignedApps	string[]	A set of manually assigned applications.

The `AnomalyDetection` object

The anomaly detection configuration.

Element	Type	Description
outageHandling	OutageHandlingPolicy	Outage handling configuration.
loadingTimeThresholds	LoadingTimeThresholdsPolicyDto	Performance thresholds configuration.

The `OutageHandlingPolicy` object

Outage handling configuration.

Element	Type	Description
globalOutage	boolean	When enabled (`true`), generate a problem and send an alert when the monitor is unavailable at all configured locations.
globalOutagePolicy	GlobalOutagePolicy	Global outage handling configuration. Can be `null`.
localOutage	boolean	When enabled (`true`), generate a problem and send an alert when the monitor is unavailable for one or more consecutive runs at any location.
localOutagePolicy	LocalOutagePolicy	Local outage handling configuration. Alert if affectedLocations of locations are unable to access the web application consecutiveRuns times consecutively.
retryOnError	boolean	Schedule retry if browser monitor execution results in a fail. For HTTP monitors this property is ignored. Can be `null`.

The `GlobalOutagePolicy` object

Global outage handling configuration.

Element	Type	Description
consecutiveRuns	integer	Alert if all locations are unable to access the web application X times consecutively.

The `LocalOutagePolicy` object

Local outage handling configuration.

Alert if affectedLocations of locations are unable to access the web application consecutiveRuns times consecutively.

Element	Type	Description
affectedLocations	integer	The number of affected locations to trigger an alert.
consecutiveRuns	integer	The number of consecutive fails to trigger an alert.

The `LoadingTimeThresholdsPolicyDto` object

Performance thresholds configuration.

Element	Type	Description
enabled	boolean	Performance threshold is enabled (`true`) or disabled (`false`).
thresholds	LoadingTimeThreshold[]	The list of performance threshold rules.

The `LoadingTimeThreshold` object

The performance threshold rule.

Element	Type	Description
type	string	The type of the threshold: total loading time or action loading time. The element can hold these values `ACTION` `TOTAL`
valueMs	integer	Notify if monitor takes longer than X milliseconds to load.
requestIndex	integer	Specify the request to which an ACTION threshold applies. Can be `null`.
eventIndex	integer	Specify the event to which an ACTION threshold applies. Can be `null`.

The `TagWithSourceInfo` object

Tag with source of a Dynatrace entity.

Element	Type	Description
source	string	The source of the tag, such as USER, RULE_BASED or AUTO The element can hold these values `AUTO` `RULE_BASED` `USER` Can be `null`.
context	string	The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the `CONTEXTLESS` value. The element can hold these values `AWS` `AWS_GENERIC` `AZURE` `CLOUD_FOUNDRY` `CONTEXTLESS` `ENVIRONMENT` `GOOGLE_CLOUD` `KUBERNETES`
key	string	The key of the tag. Custom tags have the tag value here.
value	string	The value of the tag. Not applicable to custom tags. Can be `null`.

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

json
{
  "frequencyMin": 5,
  "anomalyDetection": {
    "outageHandling": {
      "globalOutage": true,
      "localOutage": true,
      "localOutagePolicy": {
        "affectedLocations": 1,
        "consecutiveRuns": 3
      }
    },
    "loadingTimeThresholds": {
      "enabled": true,
      "thresholds": [
        {
          "type": "TOTAL",
          "valueMs": 100,
          "requestIndex": 1
        }
      ]
    }
  },
  "type": "BROWSER",
  "name": "Browser Monitor Example",
  "locations": [
    "GEOLOCATION-9999453BE4BDB3CD"
  ],
  "enabled": true,
  "script": {
    "type": "availability",
    "version": "1.0",
    "configuration": {
      "device": {
        "deviceName": "Desktop",
        "orientation": "landscape"
      }
    },
    "events": [
      {
        "type": "navigate",
        "description": "Loading of \"example.com\"",
        "url": "http://example.com",
        "wait": {
          "waitFor": "page_complete"
        }
      }
    ]
  },
  "keyPerformanceMetrics": {
    "loadActionKpm": "VISUALLY_COMPLETE",
    "xhrActionKpm": "VISUALLY_COMPLETE"
  },
  "tags": [
    "example"
  ],
  "manuallyAssignedApps": [
    "APPLICATION-4ADF0EF407C7C545"
  ],
  "events": []
}

Response

Response codes

Code	Description
204	Success. The synthetic monitor has been updated. The response doesn't have a body.

Example

In this example, the request updates the dynatrace.com monitor from the GET monitor example, changing the list of locations from which it is executed and increasing the frequency to 10 minutes.

The API token is passed in the Authorization header.

Since the request body is lengthy, it is truncated in this example Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own. Before using it, make sure that the location from the example is available in your environment. You can fetch the list of available locations with the GET all synthetic locations call. If the location is not available, replace it with any location you're using.

Curl

shell
curl -X PUT \
  https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/monitors/SYNTHETIC_TEST-0000000000025434 \
  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \
  -d '{<truncated - see the Request body section > }
'

Request URL

plaintext
https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/monitors/SYNTHETIC_TEST-0000000000025434

Request body

json
{
  "frequencyMin": 10,
  "anomalyDetection": {
    "outageHandling": {
      "globalOutage": true,
      "localOutage": false,
      "localOutagePolicy": {
        "affectedLocations": 1,
        "consecutiveRuns": 3
      }
    },
    "loadingTimeThresholds": {
      "enabled": false,
      "thresholds": []
    }
  },
  "type": "browser",
  "name": "dynatrace.com",
  "locations": [
    "GEOLOCATION-0A41430434C388A9",
    "GEOLOCATION-95196F3C9A4F4215",
    "GEOLOCATION-0DF9A0E1095A5A62"
  ],
  "enabled": true,
  "script": {
    "type": "clickpath",
    "version": "1.0",
    "configuration": {
      "device": {
        "deviceName": "Desktop",
        "orientation": "landscape"
      }
    },
    "events": [
      {
        "type": "navigate",
        "description": "Loading of \"http://www.dynatrace.com\"",
        "url": "http://www.dynatrace.com",
        "wait": {
          "waitFor": "page_complete"
        }
      },
      {
        "type": "click",
        "description": "click on \"Free trial\"",
        "target": {
          "locators": [
            {
              "type": "css",
              "value": "a:contains(\"Free trial\"):eq(1)"
            },
            {
              "type": "css",
              "value": ".btn:eq(1)"
            },
            {
              "type": "css",
              "value": "#content div div div div div div div p:nth-child(3) a"
            },
            {
              "type": "css",
              "value": "#content div.homepage-hero-wrapper div.gallery div.flickity-viewport div.flickity-slider div.gallery-cell div.section div.column p.cta--row a.btn:eq(0)"
            }
          ]
        },
        "button": 0,
        "wait": {
          "waitFor": "page_complete"
        }
      },
      {
        "type": "click",
        "description": "click on \"email\"",
        "target": {
          "locators": [
            {
              "type": "css",
              "value": "input[type=\"email\"][name=\"email\"]:eq(0)"
            },
            {
              "type": "dom",
              "value": "document.forms[0][\"email\"]"
            },
            {
              "type": "css",
              "value": ".inputfield:eq(0)"
            },
            {
              "type": "css",
              "value": "#content div div:nth-child(2) form:nth-child(9) input:nth-child(3)"
            },
            {
              "type": "css",
              "value": "#content div.section div.tile form.cta input.inputfield:eq(0)"
            }
          ]
        },
        "button": 0
      },
      {
        "type": "keystrokes",
        "description": "keystrokes on \"email\"",
        "target": {
          "locators": [
            {
              "type": "css",
              "value": "input[type=\"email\"][name=\"email\"]:eq(0)"
            },
            {
              "type": "dom",
              "value": "document.forms[0][\"email\"]"
            },
            {
              "type": "css",
              "value": ".inputfield:eq(0)"
            },
            {
              "type": "css",
              "value": "#content div div:nth-child(2) form:nth-child(9) input:nth-child(3)"
            },
            {
              "type": "css",
              "value": "#content div.section div.tile form.cta input.inputfield:eq(0)"
            }
          ]
        },
        "textValue": "sample@sample.com",
        "masked": false,
        "simulateBlurEvent": true
      },
      {
        "type": "click",
        "description": "click on \"Start free trial\"",
        "target": {
          "locators": [
            {
              "type": "css",
              "value": "input[type=\"submit\"]:eq(0)"
            },
            {
              "type": "dom",
              "value": "document.forms[0][19]"
            },
            {
              "type": "css",
              "value": ".btn:eq(1)"
            },
            {
              "type": "css",
              "value": "#content div div:nth-child(2) form:nth-child(9) div:nth-child(22) input"
            },
            {
              "type": "css",
              "value": "#content div.section div.tile form.cta div.cta__formgroup input.btn:eq(0)"
            }
          ]
        },
        "button": 0,
        "wait": {
          "waitFor": "page_complete"
        }
      }
    ]
  },
  "tags": []
}

Response code

204

Synthetic monitors API - PUT a monitor

Authentication

Parameters

Request body objects

The SyntheticMonitorUpdate object

The AnomalyDetection object

The OutageHandlingPolicy object

The GlobalOutagePolicy object

The LocalOutagePolicy object

The LoadingTimeThresholdsPolicyDto object

The LoadingTimeThreshold object

The TagWithSourceInfo object

Request body JSON model

Response

Response codes

Example

Curl

Request URL

Request body

Response code

The `SyntheticMonitorUpdate` object

The `AnomalyDetection` object

The `OutageHandlingPolicy` object

The `GlobalOutagePolicy` object

The `LocalOutagePolicy` object

The `LoadingTimeThresholdsPolicyDto` object

The `LoadingTimeThreshold` object

The `TagWithSourceInfo` object