Synthetic monitors API - POST a monitor

Creates a new synthetic monitor.

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

  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/monitors
  • SaaS https://{your-environment-id}
  • Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v1/synthetic/monitors


To execute this request, you need the Create and read synthetic monitors, locations, and nodes (ExternalSyntheticIntegration) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.


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

Parameter Type Description In Required
body SyntheticMonitorUpdate

The JSON body of the request, containing parameters of the new synthetic monitor.

body optional

Body format

The SyntheticMonitorUpdate object

The synthetic monitor update. This is a base object, the exact type depends on the value of the type field.

Element Type Description Required
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 optional
type string

Defines the actual set of fields depending on the value. See one of the following objects:

  • BROWSER -> BrowserSyntheticMonitorUpdate
  • HTTP -> HttpSyntheticMonitorUpdate
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 TagWithSourceInfo object

Tag with source of a Dynatrace entity.

Element Type Description Required
source string

The source of the tag, such as USER, RULE_BASED or AUTO

context string

The origin of the tag, such as AWS or Cloud Foundry.

Custom tags use the CONTEXTLESS value.

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.


The AnomalyDetection object

The anomaly detection configuration.

Element Type Description Required
outageHandling OutageHandlingPolicy optional
loadingTimeThresholds LoadingTimeThresholdsPolicyDto optional

The LoadingTimeThresholdsPolicyDto object

Performance thresholds configuration.

Element Type Description Required
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 Required
type string

The type of the threshold: total loading time or action loading time.

valueMs integer

Notify if monitor takes longer than X milliseconds to load.

requestIndex integer

Specify the request to which an ACTION threshold applies.

eventIndex integer

Specify the event to which an ACTION threshold applies.


The OutageHandlingPolicy object

Outage handling configuration.

Element Type Description Required
globalOutage boolean

When enabled (true), generate a problem and send an alert when the monitor is unavailable at all configured locations.

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 required
retryOnError boolean

Schedule retry if browser monitor execution results in a fail. For HTTP monitors this property is ignored.


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 Required
affectedLocations integer

The number of affected locations to trigger an alert.

consecutiveRuns integer

The number of consecutive fails to trigger an alert.



Response codes

Code Description

Success. The new synthetic monitor has been created. The response contains the Dynatrace entity ID of the new monitor.

Response body

The EntityIdDto object

A DTO for entity ID.

Element Type Description
entityId string

Entity ID to be transferred


In this example, the request creates a simple browser monitor that navigates to

The monitor is executed every 10 minutes from one location, which has the ID of GEOLOCATION-0A41430434C388A9. A problem will be raised if the website is unavailable for three consecutive runs. A notification is sent if the website takes longer than 500 milliseconds to load.

The API token is passed in the Authorization header.

The response contains the entity ID of the newly created monitor.

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 -X POST \ \
  -H 'Authorization: Api-Token abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \
  -d '{<truncated - see the Request body section >}'

Request URL

Request body

  "frequencyMin": 10,
  "anomalyDetection": {
    "outageHandling": {
      "globalOutage": true,
      "localOutage": false,
      "localOutagePolicy": {
        "affectedLocations": 1,
        "consecutiveRuns": 3
    "loadingTimeThresholds": {
      "enabled": true,
      "thresholds": [
          "type": "total",
          "valueMs": 500
  "type": "BROWSER",
  "name": "restExample",
  "locations": [
  "enabled": true,
  "script": {
    "configuration": {
      "device": {
        "orientation": "landscape",
        "deviceName": "Desktop"
    "type": "clickpath",
    "version": "1.0",
    "events": [
        "type": "navigate",
        "wait": {
        "description": "navigate to main page ",
  "tags": [

Response body

  "entityId": "SYNTHETIC_TEST-00000000000254E2"

Response code