• Home
  • Dynatrace API
  • Environment
  • Synthetic v1
  • Third party
  • POST third-party monitors

Third-party synthetic API - POST third-party monitors to Dynatrace

Pushes third-party synthetic monitors, locations, and monitor execution results to Dynatrace.

The request consumes an application/json payload.

POSTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/synthetic/ext/tests
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/ext/tests
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v1/synthetic/ext/tests

Authentication

To execute this request, you need an access token with ExternalSyntheticIntegration scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
body3rdPartySyntheticTests

The JSON body of the request. Contains third-party synthetic monitors, locations, and results.

bodyrequired

Request body objects

The 3rdPartySyntheticTests object

ElementTypeDescriptionRequired
syntheticEngineNamestring

The type of the third-party synthetic monitor.

required
syntheticEngineIconUrlstring

The URL of the third-party synthetic monitor icon.

optional
messageTimestampinteger

The timestamp of the message creation, in UTC milliseconds.

required
locations3rdPartySyntheticLocation[]

The list of third-party synthetic locations.

required
tests3rdPartySyntheticMonitor[]

The list of third-party synthetic monitors.

required
testResults3rdPartySyntheticTestResult[]

The list of results of third-party synthetic monitor execution.

optional

The 3rdPartySyntheticLocation object

The third-party Synthetic location.

ElementTypeDescriptionRequired
idstring

The ID of the location.

required
namestring

The name of the location, displayed in the UI.

required
ipstring

The IP address of the location.

optional

The 3rdPartySyntheticMonitor object

The third-party synthetic monitor.

ElementTypeDescriptionRequired
idstring

The ID of the monitor.

required
titlestring

The name of the monitor.

required
descriptionstring

A description of the monitor.

optional
testSetupstring

The information on monitor setup, for example browser.

optional
expirationTimestampinteger

The timestamp of the monitor expiration, in UTC milliseconds.

optional
drilldownLinkstring

The URL to the results of monitor execution.

optional
editLinkstring

The URL to edit the monitor in the original UI.

optional
enabledboolean

The monitor is enabled (true) or disabled (false). Default is true.

If true, set the deleted parameter to false.

optional
deletedboolean

The flag of the deleted monitor. Default is false.

If true, set the enabled parameter to false.

optional
locationsSyntheticTestLocation[]

Locations from which the synthetic monitor runs.

required
stepsSyntheticTestStep[]

Steps of the third-party monitor.

optional
scheduleIntervalInSecondsinteger

The frequency of the monitor, in seconds. The monitor is repeated with the specified interval at the third-party source.

Dynatrace expects results of a monitor execution with the specified interval. If you report results to Dynatrace less often, adjust the noDataTimeout value accordingly.

required
noDataTimeoutinteger

The timeout of the monitor, in seconds. If no result is reported within this time, the availability state switches to unmonitored. Default is doubled frequency of the monitor.

optional

The SyntheticTestLocation object

Synthetic test location.

ElementTypeDescriptionRequired
idstring

The ID of the location.

required
enabledboolean

The location is enabled/disabled. Default is true, enabling the location.

optional

The SyntheticTestStep object

The step of a synthetic monitor.

ElementTypeDescriptionRequired
idinteger

The ID of the step.

required
titlestring

The name of the step, displayed in the UI.

required

The 3rdPartySyntheticTestResult object

The results of third-party synthetic monitor execution.

ElementTypeDescriptionRequired
idstring

The ID of the third-party synthetic monitor.

required
totalStepCountinteger

Number of steps in the monitor. Defaults to number of SyntheticTestSteps.

optional
locationResults3rdPartySyntheticLocationTestResult[]

Results of third-party monitor executions per location.

required

The 3rdPartySyntheticLocationTestResult object

Results of third-party monitor executions per location.

ElementTypeDescriptionRequired
idstring

The ID of the location.

required
startTimestampinteger

The timestamp of text execution start, in UTC milliseconds.

required
successRatenumber

The overall availability of the monitor from this location, percent.

If absent, calculated as the number of successful steps compared to the overall number of steps.

optional
successboolean

If the test was successful (true) or failed (false) - will influence availability timeseries.

required
responseTimeMillisinteger

The overall response time of the monitor from this location, in milliseconds.

If absent, it is calculated as the sum of response times of all steps.

optional
stepResultsSyntheticMonitorStepResult[]

Results of individual monitor steps.

required

The SyntheticMonitorStepResult object

The result of the individual step of a synthetic monitor.

ElementTypeDescriptionRequired
idinteger

ID of the step. It is unique within the test definition.

required
startTimestampinteger

The timestamp of test step execution, UTC milliseconds.

required
responseTimeMillisinteger

The response time of the step, in milliseconds.

Absent when no meaningful response time is available (as may be the case for certain error conditions such as a misconfigured step script).

optional
errorSyntheticMonitorError

The error message of a synthetic monitor step.

optional

The SyntheticMonitorError object

The error message of a synthetic monitor step.

ElementTypeDescriptionRequired
codeinteger

The error code.

required
messagestring

The error message.

required

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
{ "syntheticEngineName": "string", "syntheticEngineIconUrl": "string", "messageTimestamp": 1, "locations": [ { "id": "string", "name": "string", "ip": "string" } ], "tests": [ { "id": "string", "title": "string", "description": "string", "testSetup": "string", "expirationTimestamp": 1, "drilldownLink": "string", "editLink": "string", "enabled": true, "deleted": true, "locations": [ { "id": "string", "enabled": true } ], "steps": [ { "id": 1, "title": "string" } ], "scheduleIntervalInSeconds": 1, "noDataTimeout": 1 } ], "testResults": [ { "id": "string", "totalStepCount": 1, "locationResults": [ { "id": "string", "startTimestamp": 1, "successRate": 1, "success": true, "responseTimeMillis": 1, "stepResults": [ { "id": 1, "startTimestamp": 1, "responseTimeMillis": 1, "error": { "code": 1, "message": "string" } } ] } ] } ] }

Response

Response codes

CodeTypeDescription
204

Success. The information is accepted and stored.

400ErrorEnvelope

Failed. The input is invalid.

Example

In this example, the request pushes the following data from third-party synthetic engine My third-party synthetic to Dynatrace:

  • Three locations: Linz1, Linz2, and Linz3.
  • Two monitors: example of synthetic monitor - 1 and example of synthetic monitor - 2, each containing three steps and running from two locations.
  • One result per step, per location, for each monitor.

Monitors have the following parameters:

example of synthetic monitor - 1example of synthetic monitor - 2
Frequency300 seconds (5 minutes)300 seconds (5 minutes)
LocationsLinz1
Linz2
Linz2
Linz3
StepsStep1-1
Step1-2
Step1-3
Step2-1
Step2-2
Step3-3

The example of synthetic monitor - 1 monitor has the following response times in milliseconds:

Linz1Linz2
Step1-177902075
Step1-220734079
Step1-386503937

The example of synthetic monitor - 2 monitor has the following response times in milliseconds:

Linz2Linz3
Step2-122009123
Step2-269039722
Step2-348211717

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 the request body JSON to perform a sample request in your environment. Be sure to replace the timestamps with recent ones or the results will be too old.

Curl

bash
curl -X POST \ https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/ext/tests \ -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/ext/tests

Request body

json
{ "syntheticEngineName": "My third-party synthetic", "syntheticEngineIconUrl": "https://static.thenounproject.com/png/1745-200.png", "messageTimestamp": 1543572265528, "locations": [ { "id": "Linz1", "ip": "127.0.0.1", "name": "Linz1" }, { "id": "Linz2", "ip": "127.0.0.2", "name": "Linz2" }, { "id": "Linz3", "ip": "127.0.0.3", "name": "Linz3" } ], "tests": [ { "id": "3rdPartySyntheticMonitor1", "title": "example of synthetic monitor - 1", "scheduleIntervalInSeconds": 300, "locations": [ { "id": "Linz1" }, { "id": "Linz2" } ], "steps": [ { "id": 1, "title": "Step1-1" }, { "id": 2, "title": "Step1-2" }, { "id": 3, "title": "Step1-3" } ] }, { "id": "3rdPartySyntheticMonitor2", "title": "example of synthetic monitor - 2", "scheduleIntervalInSeconds": 300, "locations": [ { "id": "Linz2" }, { "id": "Linz3" } ], "steps": [ { "id": 1, "title": "Step2-1" }, { "id": 2, "title": "Step2-2" }, { "id": 3, "title": "Step2-3" } ] } ], "testResults": [ { "id": "3rdPartySyntheticMonitor1", "totalStepCount": 3, "locationResults": [ { "id": "Linz1", "startTimestamp": 1543572262538, "success": true, "stepResults": [ { "id": 1, "startTimestamp": 1543572262538, "responseTimeMillis": 7790 }, { "id": 2, "startTimestamp": 1543572262538, "responseTimeMillis": 2073 }, { "id": 3, "startTimestamp": 1543572262538, "responseTimeMillis": 8650 } ] }, { "id": "Linz2", "startTimestamp": 1543572262548, "success": true, "stepResults": [ { "id": 1, "startTimestamp": 1543572262548, "responseTimeMillis": 2075 }, { "id": 2, "startTimestamp": 1543572262548, "responseTimeMillis": 4079 }, { "id": 3, "startTimestamp": 1543572262548, "responseTimeMillis": 3937 } ] } ] }, { "id": "3rdPartySyntheticMonitor2", "totalStepCount": 3, "locationResults": [ { "id": "Linz2", "startTimestamp": 1543572262548, "success": true, "stepResults": [ { "id": 1, "startTimestamp": 1543572262548, "responseTimeMillis": 2200 }, { "id": 2, "startTimestamp": 1543572262548, "responseTimeMillis": 6903 }, { "id": 3, "startTimestamp": 1543572262548, "responseTimeMillis": 4821 } ] }, { "id": "Linz3", "startTimestamp": 1543572262558, "success": true, "stepResults": [ { "id": 1, "startTimestamp": 1543572262558, "responseTimeMillis": 9123 }, { "id": 2, "startTimestamp": 1543572262558, "responseTimeMillis": 9722 }, { "id": 3, "startTimestamp": 1543572262558, "responseTimeMillis": 1717 } ] } ] } ] }

Response code

204

Result

Highlight shows parameters, submitted in the request.

External synthetic monitorsExternal synthetic monitor details