• Home
  • Dynatrace API
  • Environment
  • Maintenance windows

Maintenance windows environment API

This API is deprecated. Use the Settings API with the Maintenance windows (builtin:alerting.maintenance-window) schema instead.

Dynatrace uses maintenance windows to ensure accurate monitoring data during planned maintenance of your systems.

The Maintenance windows API enables you to use 3rd party tools to manage maintenance windows and downtimes within a monitored environment. You can:

  • Get all the maintenance windows in your environment with the GET all maintenance windows call.
  • Create or update a maintenance window with the POST a maintenance window call.
  • List the details of a specific maintenance window with the GET a maintenance window call.
  • Delete a specific maintenance window with the DELETE a maintenance window call.

GET all maintenance windows

Lists all maintenance windows (and their parameters) available in your Dynatrace environment.

The request produces an application/json payload.

GETManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/maintenance
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/maintenance
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v1/maintenance

Authentication

To execute this request, you need an access token with MaintenanceWindows scope.

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

Parameters
ParameterTypeDescriptionInRequired
frominteger

The start timestamp of the inquiry timeframe, in UTC milliseconds.

If not set, the current time is used.

queryoptional
tointeger

The end timestamp of the inquiry timeframe, in UTC milliseconds.

If not set, all maintenance windows beginning after the from timestamp will be returned.

queryoptional
typestring

The type of the maintenance window to return.

If Unknown or not set, all maintenance windows are returned.

The element can hold these values
  • Planned
  • Unknown
  • Unplanned
queryoptional
Response format

The returns an array of such objects, each representing a maintenance window.

Response codes

CodeTypeDescription
200MaintenanceWindow[]

Success

Response body objects

The ResponseBody object

The object doesn't provide any parameters.

The MaintenanceWindow object

Parameters of the maintenance window.

ElementTypeDescription
idstring

The ID of the maintenance window.

typestring

The type of the maintenance: planned or unplanned.

The element can hold these values
  • Planned
  • Unplanned
descriptionstring

A short description of the maintenance purpose.

suppressAlertsboolean

Alerting during maintenance is enabled (false) or disabled (true).

suppressProblemsboolean

Problem detection during maintenance is enabled (false) or disabled (true).

scopeMaintenanceWindowScope

An object defining the scope of your maintenance window.

You can specify particular Dynatrace entities or matching rules for dynamic formation of the scope.

If no scope is specified, the maintenance applies to the entire environment.

To specify the scope at least one entity or matching rule must be specified.

scheduleMaintenanceWindowSchedule

An object defining date, time, and recurrence of the maintenance window.

The MaintenanceWindowScope object

An object defining the scope of your maintenance window.

You can specify particular Dynatrace entities or matching rules for dynamic formation of the scope.

If no scope is specified, the maintenance applies to the entire environment.

To specify the scope at least one entity or matching rule must be specified.

ElementTypeDescription
entitiesstring[]

Defines Dynatrace entities to be included in scope, for example hosts, services, process groups.

Allowed values are Dynatrace entity IDs.

matchesMonitoredEntityFilter[]

An object defining a matching rule for dynamic scope formation. An empty rule matches for all entities.

The MonitoredEntityFilter object

Filters monitored entities by their type/tags.

ElementTypeDescription
typestring

The type of the Dynatrace entities (for example, hosts or services) you want to pick up by matching.

The element can hold these values
  • APM_SECURITY_GATEWAY
  • APPLICATION
  • APPLICATION_METHOD
  • APPLICATION_METHOD_GROUP
  • APPMON_SERVER
  • APPMON_SYSTEM_PROFILE
  • AUTO_SCALING_GROUP
  • AUXILIARY_SYNTHETIC_TEST
  • AWS_APPLICATION_LOAD_BALANCER
  • AWS_AVAILABILITY_ZONE
  • AWS_CREDENTIALS
  • AWS_LAMBDA_FUNCTION
  • AWS_NETWORK_LOAD_BALANCER
  • AZURE_API_MANAGEMENT_SERVICE
  • AZURE_APPLICATION_GATEWAY
  • AZURE_APP_SERVICE_PLAN
  • AZURE_COSMOS_DB
  • AZURE_CREDENTIALS
  • AZURE_EVENT_HUB
  • AZURE_EVENT_HUB_NAMESPACE
  • AZURE_FUNCTION_APP
  • AZURE_IOT_HUB
  • AZURE_LOAD_BALANCER
  • AZURE_MGMT_GROUP
  • AZURE_REDIS_CACHE
  • AZURE_REGION
  • AZURE_SERVICE_BUS_NAMESPACE
  • AZURE_SERVICE_BUS_QUEUE
  • AZURE_SERVICE_BUS_TOPIC
  • AZURE_SQL_DATABASE
  • AZURE_SQL_ELASTIC_POOL
  • AZURE_SQL_SERVER
  • AZURE_STORAGE_ACCOUNT
  • AZURE_SUBSCRIPTION
  • AZURE_TENANT
  • AZURE_VM
  • AZURE_VM_SCALE_SET
  • AZURE_WEB_APP
  • BROWSER
  • CF_APPLICATION
  • CF_FOUNDATION
  • CINDER_VOLUME
  • CLOUD_APPLICATION
  • CLOUD_APPLICATION_INSTANCE
  • CLOUD_APPLICATION_NAMESPACE
  • CLOUD_NETWORK_INGRESS
  • CLOUD_NETWORK_POLICY
  • CONTAINER_GROUP
  • CONTAINER_GROUP_INSTANCE
  • CUSTOM_APPLICATION
  • CUSTOM_DEVICE
  • CUSTOM_DEVICE_GROUP
  • DCRUM_APPLICATION
  • DCRUM_SERVICE
  • DCRUM_SERVICE_INSTANCE
  • DEVICE_APPLICATION_METHOD
  • DEVICE_APPLICATION_METHOD_GROUP
  • DISK
  • DOCKER_CONTAINER_GROUP
  • DOCKER_CONTAINER_GROUP_INSTANCE
  • DYNAMO_DB_TABLE
  • EBS_VOLUME
  • EC2_INSTANCE
  • ELASTIC_LOAD_BALANCER
  • ENVIRONMENT
  • EXTERNAL_SYNTHETIC_TEST_STEP
  • GCP_ZONE
  • GEOLOCATION
  • GEOLOC_SITE
  • GOOGLE_COMPUTE_ENGINE
  • HOST
  • HOST_GROUP
  • HTTP_CHECK
  • HTTP_CHECK_STEP
  • HYPERVISOR
  • HYPERVISOR_CLUSTER
  • HYPERVISOR_DISK
  • KUBERNETES_CLUSTER
  • KUBERNETES_NODE
  • KUBERNETES_SERVICE
  • MOBILE_APPLICATION
  • MULTIPROTOCOL_MONITOR
  • NETWORK_INTERFACE
  • NEUTRON_SUBNET
  • OPENSTACK_PROJECT
  • OPENSTACK_REGION
  • OPENSTACK_VM
  • OS
  • PROCESS_GROUP
  • PROCESS_GROUP_INSTANCE
  • QUEUE
  • QUEUE_INSTANCE
  • RELATIONAL_DATABASE_SERVICE
  • S3BUCKET
  • SERVICE
  • SERVICE_INSTANCE
  • SERVICE_METHOD
  • SERVICE_METHOD_GROUP
  • SWIFT_CONTAINER
  • SYNTHETIC_LOCATION
  • SYNTHETIC_TEST
  • SYNTHETIC_TEST_STEP
  • VCENTER
  • VIRTUALMACHINE
  • VMWARE_DATACENTER
tagsUniversalTag[]

The tag you want to use for matching.

You can use custom tags from the UI, AWS tags, Cloud Foundry tags, OpenShift/Kubernetes, and tags based on environment variables.

The UniversalTag object

ElementTypeDescription
tagKeyUniversalTagKey-
valuestring

The value of the tag. Not applicable to custom tags.

If a tag does have a separate key and value (in the textual representation they are split by the colon ‘:’), this field is set with the actual value. Key-value pairs can occur for automatically imported tags and tags set by rules if extractors are used.

keystring

The key of the tag. For custom tags, put the tag value here.

The key allows categorization of multiple tags. It is possible that there are multiple values for a single key which will all be represented as standalone tags. Therefore, the key does not have the semantic of a map key but is more like a key of a key-value tuple. In some cases, for example custom tags, the key represents the actual tag value and the value field is not set – those are called valueless tags.

contextstring

The origin of the tag, such as AWS or Cloud Foundry. For custom tags use the CONTEXTLESS value.

The context is set for tags that are automatically imported by OneAgent (for example, from the AWS console or environment variables). It’s useful for determining the origin of tags when not manually defined, and it also helps to prevent clashes with other existing tags. If the tag is not automatically imported, CONTEXTLESS set.

The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES

The UniversalTagKey object

ElementTypeDescription
contextstring-
The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES
keystring-

The MaintenanceWindowSchedule object

An object defining date, time, and recurrence of the maintenance window.

ElementTypeDescription
typestring

Recurrence of the schedule.

The element can hold these values
  • Day
  • Month
  • Once
  • Week
timezoneIdstring

The time zone of the start and end time. Default time zone is UTC.

You can user either UTC offset UTC+01:00 format or the IANA Time Zone Database format.

maintenanceStartstring

The start date and time of the maintenance window in the yyyy-MM-dd HH:mm format.

maintenanceEndstring

The end date and time of the maintenance window in the yyyy-MM-dd HH:mm format.

recurrenceMaintenanceWindowRecurrence

The recurrence of the maintenance window.

The MaintenanceWindowRecurrence object

The recurrence of the maintenance window.

ElementTypeDescription
daystring

The day of the week for weekly maintenance.

The format is the full name of the day in upper case, for example WEDNESDAY.

The element can hold these values
  • FRIDAY
  • MONDAY
  • SATURDAY
  • SUNDAY
  • THURSDAY
  • TUESDAY
  • WEDNESDAY
dayOfMonthinteger

The day of the month for monthly maintenance.

startstring

The start time of the maintenance window. The format is HH:mm.

durationinteger

The duration of the maintenance window in minutes.

Response body JSON model

json
[ { "id": "string", "type": "Planned", "description": "string", "suppressAlerts": true, "suppressProblems": true, "scope": { "entities": [ "string" ], "matches": [ { "type": "APM_SECURITY_GATEWAY", "tags": [ { "tagKey": { "context": "AWS", "key": "string" }, "value": "string", "key": "string", "context": "AWS" } ] } ] }, "schedule": { "type": "Day", "timezoneId": "string", "maintenanceStart": "string", "maintenanceEnd": "string", "recurrence": { "day": "FRIDAY", "dayOfMonth": 1, "start": "string", "duration": 1 } } } ]
Example

In this example, the request queries all maintenance windows of the mySampleEnv environment.

Curl

plaintext
curl -L -H "Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890" \ "https://mySampleEnv.live.dynatrace.com/api/v1/maintenance"

Request URL

plaintext
GET https://mySampleEnv.live.dynatrace.com/api/v1/maintenance?api-token=abcdefjhij1234567890

Response content

json
[ { "id": "easyTravelDeployment", "type": "Planned", "description": "Monthly deployment of easyTravel update", "suppressAlerts": true, "suppressProblems": false, "scope": { "entities": [ "HOST-8CA800CE840E20E8" ], "matches": [ { "type": "PROCESS_GROUP", "tags": [ { "context": "CONTEXTLESS", "key": "easyTravel" } ] } ] }, "schedule": { "type": "Month", "timezoneId": "Europe/Vienna", "maintenanceStart": "2018-05-01 00:00", "maintenanceEnd": "2018-10-01 00:00", "recurrence": { "dayOfMonth": 8, "start": "01:00", "duration": 90 } } }, { "id": "Planned maintenance works", "type": "Planned", "description": "", "suppressAlerts": true, "suppressProblems": true, "scope": null, "schedule": { "type": "Once", "timezoneId": "UTC", "maintenanceStart": "2018-05-13 10:00", "maintenanceEnd": "2018-10-01 12:00" } } ]

Response code

200

POST a maintenance window

Creates or updates a maintenance window.

The request consumes an application/json payload.

POSTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/maintenance
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/maintenance
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v1/maintenance

Authentication

To execute this request, you need an access token with MaintenanceWindows scope.

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

Parameters
ParameterTypeDescriptionInRequired
bodyMaintenanceWindow

Parameters of the maintenance window.

bodyoptional

Request body objects

The MaintenanceWindow object

Parameters of the maintenance window.

ElementTypeDescriptionRequired
idstring

The ID of the maintenance window.

optional
typestring

The type of the maintenance: planned or unplanned.

The element can hold these values
  • Planned
  • Unplanned
required
descriptionstring

A short description of the maintenance purpose.

optional
suppressAlertsboolean

Alerting during maintenance is enabled (false) or disabled (true).

optional
suppressProblemsboolean

Problem detection during maintenance is enabled (false) or disabled (true).

optional
scopeMaintenanceWindowScope

An object defining the scope of your maintenance window.

You can specify particular Dynatrace entities or matching rules for dynamic formation of the scope.

If no scope is specified, the maintenance applies to the entire environment.

To specify the scope at least one entity or matching rule must be specified.

optional
scheduleMaintenanceWindowSchedule

An object defining date, time, and recurrence of the maintenance window.

required

The MaintenanceWindowScope object

An object defining the scope of your maintenance window.

You can specify particular Dynatrace entities or matching rules for dynamic formation of the scope.

If no scope is specified, the maintenance applies to the entire environment.

To specify the scope at least one entity or matching rule must be specified.

ElementTypeDescriptionRequired
entitiesstring[]

Defines Dynatrace entities to be included in scope, for example hosts, services, process groups.

Allowed values are Dynatrace entity IDs.

optional
matchesMonitoredEntityFilter[]

An object defining a matching rule for dynamic scope formation. An empty rule matches for all entities.

optional

The MonitoredEntityFilter object

Filters monitored entities by their type/tags.

ElementTypeDescriptionRequired
typestring

The type of the Dynatrace entities (for example, hosts or services) you want to pick up by matching.

The element can hold these values
  • APM_SECURITY_GATEWAY
  • APPLICATION
  • APPLICATION_METHOD
  • APPLICATION_METHOD_GROUP
  • APPMON_SERVER
  • APPMON_SYSTEM_PROFILE
  • AUTO_SCALING_GROUP
  • AUXILIARY_SYNTHETIC_TEST
  • AWS_APPLICATION_LOAD_BALANCER
  • AWS_AVAILABILITY_ZONE
  • AWS_CREDENTIALS
  • AWS_LAMBDA_FUNCTION
  • AWS_NETWORK_LOAD_BALANCER
  • AZURE_API_MANAGEMENT_SERVICE
  • AZURE_APPLICATION_GATEWAY
  • AZURE_APP_SERVICE_PLAN
  • AZURE_COSMOS_DB
  • AZURE_CREDENTIALS
  • AZURE_EVENT_HUB
  • AZURE_EVENT_HUB_NAMESPACE
  • AZURE_FUNCTION_APP
  • AZURE_IOT_HUB
  • AZURE_LOAD_BALANCER
  • AZURE_MGMT_GROUP
  • AZURE_REDIS_CACHE
  • AZURE_REGION
  • AZURE_SERVICE_BUS_NAMESPACE
  • AZURE_SERVICE_BUS_QUEUE
  • AZURE_SERVICE_BUS_TOPIC
  • AZURE_SQL_DATABASE
  • AZURE_SQL_ELASTIC_POOL
  • AZURE_SQL_SERVER
  • AZURE_STORAGE_ACCOUNT
  • AZURE_SUBSCRIPTION
  • AZURE_TENANT
  • AZURE_VM
  • AZURE_VM_SCALE_SET
  • AZURE_WEB_APP
  • BROWSER
  • CF_APPLICATION
  • CF_FOUNDATION
  • CINDER_VOLUME
  • CLOUD_APPLICATION
  • CLOUD_APPLICATION_INSTANCE
  • CLOUD_APPLICATION_NAMESPACE
  • CLOUD_NETWORK_INGRESS
  • CLOUD_NETWORK_POLICY
  • CONTAINER_GROUP
  • CONTAINER_GROUP_INSTANCE
  • CUSTOM_APPLICATION
  • CUSTOM_DEVICE
  • CUSTOM_DEVICE_GROUP
  • DCRUM_APPLICATION
  • DCRUM_SERVICE
  • DCRUM_SERVICE_INSTANCE
  • DEVICE_APPLICATION_METHOD
  • DEVICE_APPLICATION_METHOD_GROUP
  • DISK
  • DOCKER_CONTAINER_GROUP
  • DOCKER_CONTAINER_GROUP_INSTANCE
  • DYNAMO_DB_TABLE
  • EBS_VOLUME
  • EC2_INSTANCE
  • ELASTIC_LOAD_BALANCER
  • ENVIRONMENT
  • EXTERNAL_SYNTHETIC_TEST_STEP
  • GCP_ZONE
  • GEOLOCATION
  • GEOLOC_SITE
  • GOOGLE_COMPUTE_ENGINE
  • HOST
  • HOST_GROUP
  • HTTP_CHECK
  • HTTP_CHECK_STEP
  • HYPERVISOR
  • HYPERVISOR_CLUSTER
  • HYPERVISOR_DISK
  • KUBERNETES_CLUSTER
  • KUBERNETES_NODE
  • KUBERNETES_SERVICE
  • MOBILE_APPLICATION
  • MULTIPROTOCOL_MONITOR
  • NETWORK_INTERFACE
  • NEUTRON_SUBNET
  • OPENSTACK_PROJECT
  • OPENSTACK_REGION
  • OPENSTACK_VM
  • OS
  • PROCESS_GROUP
  • PROCESS_GROUP_INSTANCE
  • QUEUE
  • QUEUE_INSTANCE
  • RELATIONAL_DATABASE_SERVICE
  • S3BUCKET
  • SERVICE
  • SERVICE_INSTANCE
  • SERVICE_METHOD
  • SERVICE_METHOD_GROUP
  • SWIFT_CONTAINER
  • SYNTHETIC_LOCATION
  • SYNTHETIC_TEST
  • SYNTHETIC_TEST_STEP
  • VCENTER
  • VIRTUALMACHINE
  • VMWARE_DATACENTER
optional
tagsUniversalTag[]

The tag you want to use for matching.

You can use custom tags from the UI, AWS tags, Cloud Foundry tags, OpenShift/Kubernetes, and tags based on environment variables.

optional

The UniversalTag object

ElementTypeDescriptionRequired
tagKeyUniversalTagKey-optional
valuestring

The value of the tag. Not applicable to custom tags.

If a tag does have a separate key and value (in the textual representation they are split by the colon ‘:’), this field is set with the actual value. Key-value pairs can occur for automatically imported tags and tags set by rules if extractors are used.

optional
keystring

The key of the tag. For custom tags, put the tag value here.

The key allows categorization of multiple tags. It is possible that there are multiple values for a single key which will all be represented as standalone tags. Therefore, the key does not have the semantic of a map key but is more like a key of a key-value tuple. In some cases, for example custom tags, the key represents the actual tag value and the value field is not set – those are called valueless tags.

required
contextstring

The origin of the tag, such as AWS or Cloud Foundry. For custom tags use the CONTEXTLESS value.

The context is set for tags that are automatically imported by OneAgent (for example, from the AWS console or environment variables). It’s useful for determining the origin of tags when not manually defined, and it also helps to prevent clashes with other existing tags. If the tag is not automatically imported, CONTEXTLESS set.

The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES
optional

The UniversalTagKey object

ElementTypeDescriptionRequired
contextstring-
The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES
optional
keystring-optional

The MaintenanceWindowSchedule object

An object defining date, time, and recurrence of the maintenance window.

ElementTypeDescriptionRequired
typestring

Recurrence of the schedule.

The element can hold these values
  • Day
  • Month
  • Once
  • Week
required
timezoneIdstring

The time zone of the start and end time. Default time zone is UTC.

You can user either UTC offset UTC+01:00 format or the IANA Time Zone Database format.

optional
maintenanceStartstring

The start date and time of the maintenance window in the yyyy-MM-dd HH:mm format.

required
maintenanceEndstring

The end date and time of the maintenance window in the yyyy-MM-dd HH:mm format.

required
recurrenceMaintenanceWindowRecurrence

The recurrence of the maintenance window.

optional

The MaintenanceWindowRecurrence object

The recurrence of the maintenance window.

ElementTypeDescriptionRequired
daystring

The day of the week for weekly maintenance.

The format is the full name of the day in upper case, for example WEDNESDAY.

The element can hold these values
  • FRIDAY
  • MONDAY
  • SATURDAY
  • SUNDAY
  • THURSDAY
  • TUESDAY
  • WEDNESDAY
optional
dayOfMonthinteger

The day of the month for monthly maintenance.

optional
startstring

The start time of the maintenance window. The format is HH:mm.

required
durationinteger

The duration of the maintenance window in minutes.

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.

json
{ "id": "string", "type": "Planned", "description": "string", "suppressAlerts": true, "suppressProblems": true, "scope": { "entities": [ "string" ], "matches": [ { "type": "APM_SECURITY_GATEWAY", "tags": [ { "tagKey": { "context": "AWS", "key": "string" }, "value": "string", "key": "string", "context": "AWS" } ] } ] }, "schedule": { "type": "Day", "timezoneId": "string", "maintenanceStart": "string", "maintenanceEnd": "string", "recurrence": { "day": "FRIDAY", "dayOfMonth": 1, "start": "string", "duration": 1 } } }
Response format

A successful request doesn't return any content.

Example

In this example, the request creates the planned easyTravelDeployment maintenance window, which happens every 8th day of month between 01:00 and 02:30 am. It applies to host entity HOST-1A2B3C4E5F6G7H8I and all process groups that have the easyTravel tag. During the maintenance window, problems are detected but alerts are not triggered.

Curl

shell
curl -L -H "Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890" \ -H "Content-Type: application/json" \ "https://mySampleEnv.live.dynatrace.com/api/v1/maintenance" \ -d "{\"id\":\"easyTravelDeployment\",\"type\":\"Planned\",\"description\":\"Monthly deployment of easyTravel update\",\"suppressAlerts\":true,\"suppressProblems\":false,\"scope\":{\"entities\":[\"HOST-1A2B3C4E5F6G7H8I\"],\"matches\":[{\"type\":\"PROCESS_GROUP\",\"tags\":[{\"context\":\"CONTEXTLESS\",\"key\":\"easyTravel\"}]}]},\"schedule\":{\"type\":\"Month\",\"timezoneId\":\"Europe/Vienna\",\"maintenanceStart\":\"2018-05-0100:00\",\"maintenanceEnd\":\"2018-10-0100:00\",\"recurrence\":{\"dayOfMonth\":8,\"start\":\"01:00\",\"duration\":90}}}";

Request URL

plaintext
POST https://mySampleEnv.live.dynatrace.com/api/v1/maintenance

Request body

json
{ "id": "easyTravelDeployment", "type": "Planned", "description": "Monthly deployment of easyTravel update", "suppressAlerts": true, "suppressProblems": false, "scope": { "entities": [ "HOST-1A2B3C4E5F6G7H8I" ], "matches": [ { "type": "PROCESS_GROUP", "tags": [ { "context": "CONTEXTLESS", "key": "easyTravel" } ] } ] }, "schedule": { "type": "Month", "timezoneId": "Europe/Vienna", "maintenanceStart": "2018-05-01 00:00", "maintenanceEnd": "2018-10-01 00:00", "recurrence": { "dayOfMonth": 8, "start": "01:00", "duration": 90 } } }

Response code

204

GET a maintenance window

Lists all parameters of a maintenance window. You can also get the list of all maintenance windows (and their parameters) available in your Dynatrace environment.

The request produces an application/json payload.

GETManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/maintenance/{uid}
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/maintenance/{uid}
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v1/maintenance/{uid}

Authentication

To execute this request, you need an access token with MaintenanceWindows scope.

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

Parameters
ParameterTypeDescriptionInRequired
uidstring

The ID of the required maintenance window.

pathrequired
Response format

The request for a particular maintenance window returns a JSON object containing all parameters of the maintenance window.

The request for all available maintenance windows returns an array of such objects.

Response codes

CodeTypeDescription
200MaintenanceWindow

Success

Response body objects

The MaintenanceWindow object

Parameters of the maintenance window.

ElementTypeDescription
idstring

The ID of the maintenance window.

typestring

The type of the maintenance: planned or unplanned.

The element can hold these values
  • Planned
  • Unplanned
descriptionstring

A short description of the maintenance purpose.

suppressAlertsboolean

Alerting during maintenance is enabled (false) or disabled (true).

suppressProblemsboolean

Problem detection during maintenance is enabled (false) or disabled (true).

scopeMaintenanceWindowScope

An object defining the scope of your maintenance window.

You can specify particular Dynatrace entities or matching rules for dynamic formation of the scope.

If no scope is specified, the maintenance applies to the entire environment.

To specify the scope at least one entity or matching rule must be specified.

scheduleMaintenanceWindowSchedule

An object defining date, time, and recurrence of the maintenance window.

The MaintenanceWindowScope object

An object defining the scope of your maintenance window.

You can specify particular Dynatrace entities or matching rules for dynamic formation of the scope.

If no scope is specified, the maintenance applies to the entire environment.

To specify the scope at least one entity or matching rule must be specified.

ElementTypeDescription
entitiesstring[]

Defines Dynatrace entities to be included in scope, for example hosts, services, process groups.

Allowed values are Dynatrace entity IDs.

matchesMonitoredEntityFilter[]

An object defining a matching rule for dynamic scope formation. An empty rule matches for all entities.

The MonitoredEntityFilter object

Filters monitored entities by their type/tags.

ElementTypeDescription
typestring

The type of the Dynatrace entities (for example, hosts or services) you want to pick up by matching.

The element can hold these values
  • APM_SECURITY_GATEWAY
  • APPLICATION
  • APPLICATION_METHOD
  • APPLICATION_METHOD_GROUP
  • APPMON_SERVER
  • APPMON_SYSTEM_PROFILE
  • AUTO_SCALING_GROUP
  • AUXILIARY_SYNTHETIC_TEST
  • AWS_APPLICATION_LOAD_BALANCER
  • AWS_AVAILABILITY_ZONE
  • AWS_CREDENTIALS
  • AWS_LAMBDA_FUNCTION
  • AWS_NETWORK_LOAD_BALANCER
  • AZURE_API_MANAGEMENT_SERVICE
  • AZURE_APPLICATION_GATEWAY
  • AZURE_APP_SERVICE_PLAN
  • AZURE_COSMOS_DB
  • AZURE_CREDENTIALS
  • AZURE_EVENT_HUB
  • AZURE_EVENT_HUB_NAMESPACE
  • AZURE_FUNCTION_APP
  • AZURE_IOT_HUB
  • AZURE_LOAD_BALANCER
  • AZURE_MGMT_GROUP
  • AZURE_REDIS_CACHE
  • AZURE_REGION
  • AZURE_SERVICE_BUS_NAMESPACE
  • AZURE_SERVICE_BUS_QUEUE
  • AZURE_SERVICE_BUS_TOPIC
  • AZURE_SQL_DATABASE
  • AZURE_SQL_ELASTIC_POOL
  • AZURE_SQL_SERVER
  • AZURE_STORAGE_ACCOUNT
  • AZURE_SUBSCRIPTION
  • AZURE_TENANT
  • AZURE_VM
  • AZURE_VM_SCALE_SET
  • AZURE_WEB_APP
  • BROWSER
  • CF_APPLICATION
  • CF_FOUNDATION
  • CINDER_VOLUME
  • CLOUD_APPLICATION
  • CLOUD_APPLICATION_INSTANCE
  • CLOUD_APPLICATION_NAMESPACE
  • CLOUD_NETWORK_INGRESS
  • CLOUD_NETWORK_POLICY
  • CONTAINER_GROUP
  • CONTAINER_GROUP_INSTANCE
  • CUSTOM_APPLICATION
  • CUSTOM_DEVICE
  • CUSTOM_DEVICE_GROUP
  • DCRUM_APPLICATION
  • DCRUM_SERVICE
  • DCRUM_SERVICE_INSTANCE
  • DEVICE_APPLICATION_METHOD
  • DEVICE_APPLICATION_METHOD_GROUP
  • DISK
  • DOCKER_CONTAINER_GROUP
  • DOCKER_CONTAINER_GROUP_INSTANCE
  • DYNAMO_DB_TABLE
  • EBS_VOLUME
  • EC2_INSTANCE
  • ELASTIC_LOAD_BALANCER
  • ENVIRONMENT
  • EXTERNAL_SYNTHETIC_TEST_STEP
  • GCP_ZONE
  • GEOLOCATION
  • GEOLOC_SITE
  • GOOGLE_COMPUTE_ENGINE
  • HOST
  • HOST_GROUP
  • HTTP_CHECK
  • HTTP_CHECK_STEP
  • HYPERVISOR
  • HYPERVISOR_CLUSTER
  • HYPERVISOR_DISK
  • KUBERNETES_CLUSTER
  • KUBERNETES_NODE
  • KUBERNETES_SERVICE
  • MOBILE_APPLICATION
  • MULTIPROTOCOL_MONITOR
  • NETWORK_INTERFACE
  • NEUTRON_SUBNET
  • OPENSTACK_PROJECT
  • OPENSTACK_REGION
  • OPENSTACK_VM
  • OS
  • PROCESS_GROUP
  • PROCESS_GROUP_INSTANCE
  • QUEUE
  • QUEUE_INSTANCE
  • RELATIONAL_DATABASE_SERVICE
  • S3BUCKET
  • SERVICE
  • SERVICE_INSTANCE
  • SERVICE_METHOD
  • SERVICE_METHOD_GROUP
  • SWIFT_CONTAINER
  • SYNTHETIC_LOCATION
  • SYNTHETIC_TEST
  • SYNTHETIC_TEST_STEP
  • VCENTER
  • VIRTUALMACHINE
  • VMWARE_DATACENTER
tagsUniversalTag[]

The tag you want to use for matching.

You can use custom tags from the UI, AWS tags, Cloud Foundry tags, OpenShift/Kubernetes, and tags based on environment variables.

The UniversalTag object

ElementTypeDescription
tagKeyUniversalTagKey-
valuestring

The value of the tag. Not applicable to custom tags.

If a tag does have a separate key and value (in the textual representation they are split by the colon ‘:’), this field is set with the actual value. Key-value pairs can occur for automatically imported tags and tags set by rules if extractors are used.

keystring

The key of the tag. For custom tags, put the tag value here.

The key allows categorization of multiple tags. It is possible that there are multiple values for a single key which will all be represented as standalone tags. Therefore, the key does not have the semantic of a map key but is more like a key of a key-value tuple. In some cases, for example custom tags, the key represents the actual tag value and the value field is not set – those are called valueless tags.

contextstring

The origin of the tag, such as AWS or Cloud Foundry. For custom tags use the CONTEXTLESS value.

The context is set for tags that are automatically imported by OneAgent (for example, from the AWS console or environment variables). It’s useful for determining the origin of tags when not manually defined, and it also helps to prevent clashes with other existing tags. If the tag is not automatically imported, CONTEXTLESS set.

The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES

The UniversalTagKey object

ElementTypeDescription
contextstring-
The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES
keystring-

The MaintenanceWindowSchedule object

An object defining date, time, and recurrence of the maintenance window.

ElementTypeDescription
typestring

Recurrence of the schedule.

The element can hold these values
  • Day
  • Month
  • Once
  • Week
timezoneIdstring

The time zone of the start and end time. Default time zone is UTC.

You can user either UTC offset UTC+01:00 format or the IANA Time Zone Database format.

maintenanceStartstring

The start date and time of the maintenance window in the yyyy-MM-dd HH:mm format.

maintenanceEndstring

The end date and time of the maintenance window in the yyyy-MM-dd HH:mm format.

recurrenceMaintenanceWindowRecurrence

The recurrence of the maintenance window.

The MaintenanceWindowRecurrence object

The recurrence of the maintenance window.

ElementTypeDescription
daystring

The day of the week for weekly maintenance.

The format is the full name of the day in upper case, for example WEDNESDAY.

The element can hold these values
  • FRIDAY
  • MONDAY
  • SATURDAY
  • SUNDAY
  • THURSDAY
  • TUESDAY
  • WEDNESDAY
dayOfMonthinteger

The day of the month for monthly maintenance.

startstring

The start time of the maintenance window. The format is HH:mm.

durationinteger

The duration of the maintenance window in minutes.

Response body JSON model

json
{ "id": "string", "type": "Planned", "description": "string", "suppressAlerts": true, "suppressProblems": true, "scope": { "entities": [ "string" ], "matches": [ { "type": "APM_SECURITY_GATEWAY", "tags": [ { "tagKey": { "context": "AWS", "key": "string" }, "value": "string", "key": "string", "context": "AWS" } ] } ] }, "schedule": { "type": "Day", "timezoneId": "string", "maintenanceStart": "string", "maintenanceEnd": "string", "recurrence": { "day": "FRIDAY", "dayOfMonth": 1, "start": "string", "duration": 1 } } }
Example

In this example, the request queries

Curl

Request URL

Response content

Response code

DELETE a maintenance window

Deletes the specified maintenance window. Deletion can't be undone.

DELETEManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/maintenance/{uid}
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/maintenance/{uid}
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v1/maintenance/{uid}

Authentication

To execute this request, you need an access token with MaintenanceWindows scope.

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

Parameters
ParameterTypeDescriptionInRequired
uidstring

The ID of the maintenance window to delete.

pathrequired
Response format

A successful request doesn't return any content.

Example

In this example, the request deletes the easyTravelDeployment maintenance window.

Curl

plaintext
curl -X DELETE "Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890" \ "https://mySampleEnv.live.dynatrace.com/api/v1/maintenance/easyTravelDeployment" \

Request URL

plaintext
DELETE https://mySampleEnv.live.dynatrace.com/api/v1/maintenance/easyTravelDeployment?api-token=abcdefjhij1234567890

Response code

204

Related topics
  • Maintenance windows

    Understand when to use a maintenance window. Read about the supported maintenance window types.