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.

POST
  • Managed 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

Authentication

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.

Parameters

Parameter Type Description In Required
body 3rdPartySyntheticTests

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

body optional

The 3rdPartySyntheticTests object

Element Type Description Required
syntheticEngineName string

The type of the third-party synthetic monitor.

required
syntheticEngineIconUrl string

The URL of the third-party synthetic monitor icon.

optional
messageTimestamp integer

The timestamp of the message creation, in UTC milliseconds.

required
locations 3rdPartySyntheticLocation[]

The list of third-party synthetic locations.

optional
tests 3rdPartySyntheticMonitor[]

The list of third-party synthetic monitors.

optional
testResults 3rdPartySyntheticTestResult[]

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

optional

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
scheduleIntervalInSeconds integer optional
totalStepCount integer

Number of steps in the monitor.

required
locationResults 3rdPartySyntheticLocationTestResult[]

Results of third-party monitor executions per location.

optional

The 3rdPartySyntheticLocationTestResult object

Results of third-party monitor executions per location.

Element Type Description Required
id string

The ID of the location.

required
startTimestamp integer

The timestamp of text execution start, in UTC milliseconds.

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
success boolean

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

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
stepResults SyntheticMonitorStepResult[]

Results of individual monitor steps.

optional

The SyntheticMonitorStepResult object

The result of the individual step of a synthetic monitor.

Element Type Description Required
id integer

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

required
startTimestamp integer

The timestamp of text step execution, UTC milliseconds.

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
error SyntheticMonitorError optional

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
id string

The ID of the monitor.

required
title string

The name of the monitor.

required
description string

A description of the monitor.

optional
testSetup string

The information on monitor setup, for example browser.

optional
expirationTimestamp integer

The timestamp of the monitor expiration, in UTC milliseconds.

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
deleted boolean

The flag of the deleted monitor. Default is false.

If true, set the enabled parameter to false.

optional
locations SyntheticTestLocation[]

Locations from which the synthetic monitor runs.

optional
steps SyntheticTestStep[]

Steps of the third-party 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
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

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

The SyntheticTestLocation object

Synthetic test location.

Element Type Description Required
id string

The ID of the location.

required
enabled boolean

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

optional

The 3rdPartySyntheticLocation object

The third-party Synthetic location.

Element Type Description Required
id string

The ID of the location.

required
name string

The name of the location, displayed in the UI.

required
ip string

The IP address of the location.

optional

Response format

A successful request doesn't return any content.

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) 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 time stamps 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 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

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