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

Reference

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

The request consumes an application/json payload.

POST	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/ext/tests`
POST	Environment ActiveGate	`https://{your-activegate-domain}:9999/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

Parameter	Type	Description	In	Required
body	3rdPartySyntheticTests	The JSON body of the request. Contains third-party synthetic monitors, locations, and results.	body	required

Request body objects

The `3rdPartySyntheticTests` object

Element	Type	Description	Required
locations	3rdPartySyntheticLocation[]	The list of third-party synthetic locations.	required
messageTimestamp	integer	The timestamp of the message creation, in UTC milliseconds.	required
syntheticEngineIconUrl	string	The URL of the third-party synthetic monitor icon.	optional
syntheticEngineName	string	The type of the third-party synthetic monitor.	required
testResults	3rdPartySyntheticTestResult[]	The list of results of third-party synthetic monitor execution.	optional
tests	3rdPartySyntheticMonitor[]	The list of third-party synthetic monitors.	required

The `3rdPartySyntheticLocation` object

The third-party Synthetic location.

Element	Type	Description	Required
id	string	The ID of the location.	required
ip	string	The IP address of the location.	optional
name	string	The name of the location, displayed in the UI.	required

The `3rdPartySyntheticTestResult` object

The results of third-party synthetic monitor execution.

Element	Type	Description	Required
id	string	The ID of the third-party synthetic monitor.	required
locationResults	3rdPartySyntheticLocationTestResult[]	Results of third-party monitor executions per location.	required
totalStepCount	integer	Number of steps in the monitor. Defaults to number of SyntheticTestSteps.	optional

The `3rdPartySyntheticLocationTestResult` object

Results of third-party monitor executions per location.

Element	Type	Description	Required
id	string	The ID of the location.	required
responseTimeMillis	integer	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
startTimestamp	integer	The timestamp of text execution start, in UTC milliseconds.	required
stepResults	SyntheticMonitorStepResult[]	Results of individual monitor steps.	required
success	boolean	If the test was successful (`true`) or failed (`false`) - will influence availability timeseries.	required
successRate	number	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

The `SyntheticMonitorStepResult` object

The result of the individual step of a synthetic monitor.

Element	Type	Description	Required
error	SyntheticMonitorError	The error message of a synthetic monitor step.	optional
id	integer	ID of the step. It is unique within the test definition.	required
responseTimeMillis	integer	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
startTimestamp	integer	The timestamp of test step execution, UTC milliseconds.	required

The `SyntheticMonitorError` object

The error message of a synthetic monitor step.

Element	Type	Description	Required
code	integer	The error code.	required
message	string	The error message.	required

The `3rdPartySyntheticMonitor` object

The third-party synthetic monitor.

Element	Type	Description	Required
deleted	boolean	The flag of the deleted monitor. Default is `false`. If `true`, set the enabled parameter to `false`.	optional
description	string	A description of the monitor.	optional
drilldownLink	string	The URL to the results of monitor execution.	optional
editLink	string	The URL to edit the monitor in the original UI.	optional
enabled	boolean	The monitor is enabled (`true`) or disabled (`false`). Default is `true`. If `true`, set the deleted parameter to `false`.	optional
expirationTimestamp	integer	The timestamp of the monitor expiration, in UTC milliseconds.	optional
id	string	The ID of the monitor.	required
locations	SyntheticTestLocation[]	Locations from which the synthetic monitor runs.	required
noDataTimeout	integer	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
scheduleIntervalInSeconds	integer	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
steps	SyntheticTestStep[]	Steps of the third-party monitor.	optional
testSetup	string	The information on monitor setup, for example `browser`.	optional
title	string	The name of the monitor.	required

The `SyntheticTestLocation` object

Synthetic test location.

Element	Type	Description	Required
enabled	boolean	The location is enabled/disabled. Default is `true`, enabling the location.	optional
id	string	The ID of the location.	required

The `SyntheticTestStep` object

The step of a synthetic monitor.

Element	Type	Description	Required
id	integer	The ID of the step.	required
title	string	The name of the step, displayed in the UI.	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.

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

Response

Response codes

Code	Type	Description
204	-	Success. The information is accepted and stored.
400	ErrorEnvelope	Failed. The input is invalid.
4XX	ErrorEnvelope	Client side error.
5XX	ErrorEnvelope	Server side error.

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 - 1

example of synthetic monitor - 2

Frequency

300 seconds (5 minutes)

Locations

Linz1
Linz2

Linz2
Linz3

Steps

Step1-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:

Linz1

Linz2

Step1-1

7790

2075

Step1-2

2073

4079

Step1-3

8650

3937

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

Linz2

Linz3

Step2-1

2200

9123

Step2-2

6903

9722

Step2-3

4821

1717

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

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

https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/ext/tests

Request body

{
  "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.