• 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.

POSTManaged https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/ext/tests
SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/ext/tests
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v1/synthetic/ext/tests

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

ParameterTypeDescriptionInRequired
body3rdPartySyntheticTests

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

bodyrequired

Request body objects

The 3rdPartySyntheticTests object

ElementTypeDescription
syntheticEngineNamestring

The type of the third-party synthetic monitor.

syntheticEngineIconUrlstring

The URL of the third-party synthetic monitor icon.

Can be null.

messageTimestampinteger

The timestamp of the message creation, in UTC milliseconds.

locations3rdPartySyntheticLocation[]

The list of third-party synthetic locations.

tests3rdPartySyntheticMonitor[]

The list of third-party synthetic monitors.

testResults3rdPartySyntheticTestResult[]

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

Can be null.

The 3rdPartySyntheticLocation object

The third-party Synthetic location.

ElementTypeDescription
idstring

The ID of the location.

namestring

The name of the location, displayed in the UI.

ipstring

The IP address of the location.

Can be null.

The 3rdPartySyntheticMonitor object

The third-party synthetic monitor.

ElementTypeDescription
idstring

The ID of the monitor.

titlestring

The name of the monitor.

descriptionstring

A description of the monitor.

Can be null.

testSetupstring

The information on monitor setup, for example browser.

Can be null.

expirationTimestampinteger

The timestamp of the monitor expiration, in UTC milliseconds.

Can be null.

drilldownLinkstring

The URL to the results of monitor execution.

Can be null.

editLinkstring

The URL to edit the monitor in the original UI.

Can be null.

enabledboolean

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

If true, set the deleted parameter to false.

Can be null.

deletedboolean

The flag of the deleted monitor. Default is false.

If true, set the enabled parameter to false.

Can be null.

locationsSyntheticTestLocation[]

Locations from which the synthetic monitor runs.

stepsSyntheticTestStep[]

Steps of the third-party monitor.

Can be null.

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.

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.

Can be null.

The SyntheticTestLocation object

Synthetic test location.

ElementTypeDescription
idstring

The ID of the location.

enabledboolean

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

Can be null.

The SyntheticTestStep object

The step of a synthetic monitor.

ElementTypeDescription
idinteger

The ID of the step.

titlestring

The name of the step, displayed in the UI.

The 3rdPartySyntheticTestResult object

The results of third-party synthetic monitor execution.

ElementTypeDescription
idstring

The ID of the third-party synthetic monitor.

totalStepCountinteger

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

Can be null.

locationResults3rdPartySyntheticLocationTestResult[]

Results of third-party monitor executions per location.

The 3rdPartySyntheticLocationTestResult object

Results of third-party monitor executions per location.

ElementTypeDescription
idstring

The ID of the location.

startTimestampinteger

The timestamp of text execution start, in UTC milliseconds.

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.

Can be null.

successboolean

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

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.

Can be null.

stepResultsSyntheticMonitorStepResult[]

Results of individual monitor steps.

The SyntheticMonitorStepResult object

The result of the individual step of a synthetic monitor.

ElementTypeDescription
idinteger

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

startTimestampinteger

The timestamp of test step execution, UTC milliseconds.

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).

Can be null.

errorSyntheticMonitorError

The error message of a synthetic monitor step.

Can be null.

The SyntheticMonitorError object

The error message of a synthetic monitor step.

ElementTypeDescription
codeinteger

The error code.

messagestring

The error message.

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 time stamps with recent ones or the results will be too old.

Curl

shell
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