Synthetic monitors API - POST a monitor

Creates a new synthetic monitor.

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

POST	Managed https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/monitors SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/monitors

Authentication

To execute this request, you need the Access problem and event feed, metrics, and topology permission assigned to your API token. To learn how to obtain and use it, see the Authentication page.

Parameters

Refer to JSON models to find all JSON models that depend on the type of the model.

Parameter	Type	Description	In	Required
body	SyntheticMonitorUpdate	The JSON body of the request, containing parameters of the new synthetic monitor.	body	optional

Request parameters JSON model

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`.	required
anomalyDetection	AnomalyDetection	The anomaly detection configuration.	optional
type	string	Defines the actual set of fields depending on the value. See one of the following objects: `BROWSER` -> BrowserSyntheticMonitorUpdate `HTTP` -> HttpSyntheticMonitorUpdate The type element can hold these values.	required
name	string	The name of the monitor.	required
locations	string[]	A list of locations from which the monitor is executed. To specify a location, use its entity ID.	required
enabled	boolean	The monitor is enabled (`true`) or disabled (`false`).	required
script	object	The script of a browser or HTTP monitor.	required
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.	required
manuallyAssignedApps	string[]	A set of manually assigned applications.	required

The TagWithSourceInfo object

Tag with source of a Dynatrace entity.

Element	Type	Description	Required
context	string	The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the `CONTEXTLESS` value. The context element can hold these values.	required
key	string	The key of the tag. Custom tags have the tag value here.	required
value	string	The value of the tag. Not applicable to custom tags.	optional
source	string	The source of the tag, such as USER, RULE_BASED or AUTO The source element can hold these values.	optional

The AnomalyDetection object

The anomaly detection configuration.

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

The LoadingTimeThresholdsPolicyDto object

Performance thresholds configuration.

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

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. The type element can hold these values.	required
valueMs	integer	Notify if monitor takes longer than X milliseconds to load.	required
requestIndex	integer	Specify the request to which an ACTION threshold applies.	optional

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.	required
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.	required
localOutagePolicy	LocalOutagePolicy	Local outage handling configuration.	required

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.	required
consecutiveRuns	integer	The number of consecutive fails to trigger an alert.	required

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.

      
  {
  "frequencyMin": 5,
  "anomalyDetection": {
    "outageHandling": {
      "globalOutage": true,
      "localOutage": true,
      "localOutagePolicy": {
        "affectedLocations": 1,
        "consecutiveRuns": 3
      }
    },
    "loadingTimeThresholds": {
      "enabled": true,
      "thresholds": [
        {
          "type": "TOTAL",
          "valueMs": 100,
          "requestIndex": 1
        }
      ]
    },
    "_inheritance": "SyntheticMonitorUpdate"
  },
  "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"\n",
        "url": "http://example.com",
        "wait": {
          "waitFor": "page_complete"
        }
      }
    ],
    "_inheritance": "SyntheticMonitorUpdate"
  },
  "keyPerformanceMetrics": {
    "loadActionKpm": "VISUALLY_COMPLETE",
    "xhrActionKpm": "VISUALLY_COMPLETE",
    "_inheritance": "SyntheticMonitorUpdate"
  },
  "tags": [
    "example"
  ],
  "manuallyAssignedApps": [
    "APPLICATION-4ADF0EF407C7C545"
  ],
  "events": []
}

Possible values

Possible values for the source element in the TagWithSourceInfo object:

AUTO
RULE_BASED
USER

Possible values for the context element in the TagWithSourceInfo object:

AWS
AWS_GENERIC
AZURE
CLOUD_FOUNDRY
CONTEXTLESS
ENVIRONMENT
GOOGLE_CLOUD
KUBERNETES

Possible values for the type element in the SyntheticMonitorUpdate object:

BROWSER
HTTP

Possible values for the type element in the LoadingTimeThreshold object:

ACTION
TOTAL

Response format

Response parameters JSON model

The EntityIdDto object

A DTO for entity ID.

Element	Type	Description
entityId	string	Entity ID to be transferred

    
{
  "entityId": "string"
}

Example

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

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

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

Request URL

https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/monitors

Request body


        api-examples/synthetic/post-monitor.json

Download

{
  "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": [
    "GEOLOCATION-0A41430434C388A9"
  ],
  "enabled": true,
  "script": {
    "configuration": {
      "device": {
        "orientation": "landscape",
        "deviceName": "Desktop"
      }
    },
    "type": "clickpath",
    "version": "1.0",
    "events": [
      {
        "type": "navigate",
        "wait": {
          "waitFor":"page_complete"
        },
        "description": "navigate to main page ",
        "url":"https://www.dynatrace.com"
      }
    ]
  },
  "tags": [
    "restExample"
  ]
}

Response body

{
  "entityId": "SYNTHETIC_TEST-00000000000254E2"
}

Response code

200