Synthetic monitor executions API v2 - POST batch execution

Triggers a batch execution of synthetic monitors.

The request consumes and produces an application/json payload.

POSTSaaShttps://{your-environment-id}.live.dynatrace.com/api/v2/synthetic/executions/batch
Environment ActiveGateCluster ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/synthetic/executions/batch

Authentication

To execute this request, you need an access token with one of the following scopes:

  • syntheticExecutions.write
  • ExternalSyntheticIntegration

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

Parameters

Parameter
Type
Description
In
Required
body

The JSON body of the request. Contains the parameters of the triggered on-demand execution.

body
required

Request body objects

The SyntheticOnDemandExecutionRequest object

Contains parameters for the on-demand execution of monitors identified by tags, applications, or services.

Element
Type
Description
Required
failOnPerformanceIssue
boolean

If true, the execution will fail in case of performance issue.

optional
failOnSslWarning
boolean

Applies to HTTP monitors only. If true, the execution will fail in case of an SSL certificate expiration warning or if the certificate is missing.

optional
group

Contains parameters for the on-demand execution of monitors identified by tags, applications, or services.

optional
metadata
object

String to string map of metadata properties for execution

optional
monitors

List of monitors to be triggered.

optional
processingMode
string

The execution's processing mode

  • STANDARD
  • DISABLE_PROBLEM_DETECTION
  • EXECUTIONS_DETAILS_ONLY
optional
stopOnProblem
boolean

If true, no executions will be scheduled if a problem occurs.

optional
takeScreenshotsOnSuccess
boolean

If true, the screenshots will be taken during the execution of a browser monitor.

optional

The SyntheticOnDemandExecutionRequestGroup object

Contains parameters for the on-demand execution of monitors identified by tags, applications, or services.

Element
Type
Description
Required
applications
string[]

List of application identifiers. Only monitors with all applications assigned will be executed.

optional
locations
string[]

The locations from where monitors are to be executed.

optional
services
string[]

List of service identifiers. Only monitors with all services assigned will be executed.

optional
tags
string[]

List of tags. Only monitors with all tags assigned will be executed.

optional

The SyntheticOnDemandExecutionRequestMonitor object

Contains monitors to be executed on demand from the locations specified.

Element
Type
Description
Required
customizedScript
object

Customized script properties for this on-demand batch execution.

optional
executionCount
integer

The number of times the monitor is to be executed per location; if not set, the monitor will be executed once.

optional
locations
string[]

The locations from where the monitor is to be executed.

optional
monitorId
string

The monitor identifier.

required
repeatMode
string

Execution repeat mode. If not set, the mode is SEQUENTIAL.

  • SEQUENTIAL
  • PARALLEL
optional

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.

{
  "failOnPerformanceIssue": false,
  "failOnSslWarning": true,
  "group": {
    "applications": [
      "APPLICATION-CD4BEF05FA9DD044"
    ],
    "services": [
      "SERVICE-01C6C1282960638B",
      "SERVICE-B18840B4E3115C1A"
    ],
    "tags": [
      "tag-production",
      "another-tag"
    ]
  },
  "metadata": {
    "key": "value",
    "version": "1.255.20221022"
  },
  "monitors": [
    {
      "customizedScript": {
        "requests": [
          {
            "sequenceId": "1",
            "url": "https://www.somepage.org",
            "validation": {
              "rules": [
                {
                  "passIfFound": "true",
                  "type": "httpStatusesList",
                  "value": "=201"
                }
              ]
            }
          }
        ]
      },
      "executionCount": 3,
      "locations": [
        "SYNTHETIC_LOCATION-9BB04DAEBA71B8CA",
        "SYNTHETIC_LOCATION-ACCA399FAA1194DD"
      ],
      "monitorId": "HTTP_CHECK-6349B98E1CD87352",
      "repeatMode": "SEQUENTIAL"
    }
  ],
  "processingMode": "EXECUTIONS_DETAILS_ONLY",
  "stopOnProblem": true,
  "takeScreenshotsOnSuccess": true
}

Response

Response codes

Code
Type
Description
201

Success. The monitor's execution response details

400

Failed. The input is invalid.

503

Unavailable

4XX

Client side error.

5XX

Server side error.

Response body objects

The SyntheticOnDemandExecutionResult object

The result of on-demand synthetic monitor execution.

Element
Type
Description
batchId
string

The batch identifier of the triggered executions.

triggered

Monitors for which on-demand executions were triggered.

triggeredCount
integer

The total number of the triggered executions within the batch.

triggeringProblemsCount
integer

The total number of problems within the batch.

triggeringProblemsDetails

List with the entities for which triggering problems occurred.

The SyntheticOnDemandTriggeredMonitor object

Contains the list of on-demand executions of the monitor.

Element
Type
Description
executions

The list of triggered executions.

monitorId
string

The monitor identifier.

The SyntheticOnDemandTriggeredExecutionDetails object

Contains details of the triggered on-demand execution.

Element
Type
Description
executionId
string

The execution's identifier.

locationId
string

The identifier of the location from which the monitor is to be executed.

The SyntheticOnDemandTriggeringProblemDetails object

Contains the details of problems encountered while triggering on-demand executions.

Element
Type
Description
cause
string

The cause of not triggering entity.

details
string

The details of triggering problem.

entityId
string

The entity identifier.

executionId
integer

The execution identifier.

locationId
string

The location identifier.

Response body JSON model

{
  "batchId": "22396514015719218",
  "triggered": [
    {
      "executions": [
        {
          "executionId": "1069999568093682590",
          "locationId": "SYNTHETIC_LOCATION-9BB04DAE11123122"
        }
      ],
      "monitorId": "HTTP_CHECK-69A9B98E1CD87352"
    }
  ],
  "triggeredCount": 1,
  "triggeringProblemsCount": 4,
  "triggeringProblemsDetails": [
    {
      "cause": "Location not found",
      "entityId": "HTTP_CHECK-6349B98E1CD87352",
      "locationId": "SYNTHETIC_LOCAT-9BB04DAEBA71B8CA"
    },
    {
      "cause": "Monitor not found",
      "entityId": "HTTP_CHECK-6349B98E1CD85432"
    },
    {
      "cause": "Incorrect monitor identifier format",
      "entityId": "HTTP_HACK-AAAAAAA"
    },
    {
      "cause": "Incorrect application identifier format",
      "entityId": "APPLICATION-WRONG"
    }
  ]
}

Related topics