Try it free

Trigger on-demand executions

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026
  • Early Access

Trigger on-demand synthetic monitor executions in Dynatrace with the Synthetic API, using monitor selection and execution options in the request body.

POSTSaaShttps://{your-environment-id}.apps.dynatrace.com/platform/synthetic/v1/executions/batch

Overview

You use the batch executions endpoint to start on-demand executions for synthetic monitors. The request body can include failOnPerformanceIssue, failOnSslWarning, group, metadata, monitors, processingMode, stopOnProblem, and takeScreenshotsOnSuccess, and the operation returns 201 when it creates the executions.

Authentication

To execute this request, you need a platform token or OAuth access token with synthetic:monitors:execute scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
bodySyntheticOnDemandExecutionRequest

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

bodyRequired

Request body objects

The SyntheticOnDemandExecutionRequest object

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

ElementTypeDescriptionRequired
failOnPerformanceIssueboolean

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

Optional
failOnSslWarningboolean

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
groupSyntheticOnDemandGroupExecutionRequest

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

Optional
metadataobject

String to string map of metadata properties for execution.

Optional
monitorsSyntheticOnDemandMonitorExecutionRequest[]

List of monitors to be triggered.

Optional
processingModestring

The execution's processing mode.

The element can hold these values
  • STANDARD
  • DISABLE_PROBLEM_DETECTION
  • EXECUTIONS_DETAILS_ONLY
Optional
stopOnProblemboolean

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

Optional
takeScreenshotsOnSuccessboolean

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

Optional

The SyntheticOnDemandGroupExecutionRequest object

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

ElementTypeDescriptionRequired
applicationsstring[]

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

Optional
locationsstring[]

The locations from where monitors are to be executed.

Optional
servicesstring[]

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

Optional
tagsstring[]

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

Optional

The SyntheticOnDemandMonitorExecutionRequest object

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

ElementTypeDescriptionRequired
customizedScriptobject

Customized script properties for this on-demand batch execution.

Optional
executionCountinteger

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

Optional
locationsstring[]

The locations from where the monitor is to be executed.

Optional
monitorIdstring

The monitor identifier.

Required
repeatModestring

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

The element can hold these values
  • 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_MONITOR-6349B98E1CD87352",
      "repeatMode": "SEQUENTIAL"
    }
  ],
  "processingMode": "EXECUTIONS_DETAILS_ONLY",
  "stopOnProblem": true,
  "takeScreenshotsOnSuccess": true
}

Response

Response codes

CodeTypeDescription
201SyntheticOnDemandExecutionResponse

Created

4XXErrorResponseEnvelope

Client side error.

5XXErrorResponseEnvelope

Server side error.

Response body objects

The SyntheticOnDemandExecutionResponse object

The result of on-demand synthetic monitor execution.

ElementTypeDescription
batchIdstring

The batch identifier of the triggered executions.

triggeredSyntheticOnDemandTriggeredMonitorResponse[]

Monitors for which on-demand executions were triggered.

triggeredCountinteger

The total number of the triggered executions within the batch.

triggeringProblemsCountinteger

The total number of problems within the batch.

triggeringProblemsDetailsSyntheticOnDemandTriggeringProblemDetailsResponse[]

List with the entities for which triggering problems occurred.

The SyntheticOnDemandTriggeredMonitorResponse object

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

ElementTypeDescription
executionsSyntheticOnDemandTriggeredExecutionDetailsResponse[]

The list of triggered executions.

monitorIdstring

The monitor identifier.

The SyntheticOnDemandTriggeredExecutionDetailsResponse object

Contains details of the triggered on-demand execution.

ElementTypeDescription
executionIdstring

The execution's identifier.

locationIdstring

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

The SyntheticOnDemandTriggeringProblemDetailsResponse object

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

ElementTypeDescription
causestring

The cause of not triggering entity.

detailsstring

The details of triggering problem.

executionIdstring

The execution identifier.

idstring

The entity identifier.

locationIdstring

The location identifier.

The ErrorResponseEnvelope object

Encloses the encountered error.

ElementTypeDescription
errorErrorResponse

Basic information of the encountered error.

The ErrorResponse object

Basic information of the encountered error.

ElementTypeDescription
codeinteger

The returned HTTP status code.

detailsErrorResponseDetails

Detailed information of the error.

messagestring

Description of the encountered error.

The ErrorResponseDetails object

Detailed information of the error.

ElementTypeDescription
typestring

Defines the actual set of fields depending on the value. See one of the following objects:

  • constraintViolation -> ConstraintViolationDetails
The element can hold these values
  • constraintViolation

Response body JSON models

{
  "batchId": "22396514015719218",
  "triggered": [
    {
      "executions": [
        {
          "executionId": "1069999568093682590",
          "locationId": "SYNTHETIC_LOCATION-9BB04DAE11123122"
        }
      ],
      "monitorId": "HTTP_MONITOR-69A9B98E1CD87352"
    }
  ],
  "triggeredCount": 1,
  "triggeringProblemsCount": 4,
  "triggeringProblemsDetails": [
    {
      "cause": "Location not found",
      "id": "HTTP_MONITOR-6349B98E1CD87352",
      "locationId": "SYNTHETIC_LOCAT-9BB04DAEBA71B8CA"
    },
    {
      "cause": "Monitor not found",
      "id": "HTTP_MONITOR-6349B98E1CD85432"
    },
    {
      "cause": "Incorrect monitor identifier format",
      "id": "HTTP_HACK-AAAAAAA"
    },
    {
      "cause": "Incorrect application identifier format",
      "id": "APPLICATION-WRONG"
    }
  ]
}
{
  "error": {
    "code": 1,
    "details": {
      "type": "constraintViolation"
    },
    "message": "string"
  }
}
Related tags
Platform APIDynatrace PlatformDigital Experience