Events API v1 - POST an event

This API is deprecated. Use the Events API v2 instead.

Pushes custom events from third-party integrations to one or more monitored entities.

This endpoint enables third-party systems such as CI platforms (Jenkins, Bamboo, Electric Cloud, etc.) to provide additional details for Dynatrace automated root cause analysis.

You can use this endpoint to:

Push information-only events from third-party systems to provide additional information for Dynatrace automated root cause analysis. The time of event closure is already known and the event IDs are returned instantly. You can push these events for up to 30 days into the past. The information-only event types are:
- CUSTOM_ANNOTATION
- CUSTOM_CONFIGURATION
- CUSTOM_DEPLOYMENT
- CUSTOM_INFO
- MARKED_FOR_TERMINATION
Push problem-opening events (for example, an error rate increase) to trigger the Dynatrace automated root cause analysis engine. Correlation IDs are returned instead of event IDs. These events stay open until the specified timeout expires. To prevent expiration, you can refresh these events by sending the same payload again. You can push these events for up to 60 minutes into the past. The problem-opening event types (sorted by highest to lowest severity) are:
- AVAILABILITY_EVENT
- ERROR_EVENT
- PERFORMANCE_EVENT
- RESOURCE_CONTENTION

The request consumes and produces an application/json payload.

POST	ManagedDynatrace for Government	`https://{your-domain}/e/{your-environment-id}/api/v1/events`
	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v1/events`
	Environment ActiveGate	`https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v1/events`

Authentication

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

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

Parameters

The set of parameters depends on the event type. See Parameters mapping below for details.

Parameter	Type	Description	In	Required
body	EventCreation	The JSON body of the request, containing parameters of the event.	body	optional

Request body objects

The `EventCreation` object

Configuration of the custom event.

Element	Type	Description	Required
allowDavisMerge	boolean	Allow Davis AI to merge this event into existing problems (true) or force creating a new problem (false). This only applies to problem-opening event types.	optional
annotationDescription	string	A detailed description of the custom annotation, for example `DNS route has been changed to x.mydomain.com`.	optional
annotationType	string	The type of the custom annotation, for example `DNS route has been changed`.	optional
attachRules	PushEventAttachRules	The set of rules defining Dynatrace entities to be associated with the event. You can specify tags to dynamically match Dynatrace entities or IDs of specific entities. At least one entity ID or tag is required.	required
changed	string	The new value of the configuration that has been set by the event.	optional
ciBackLink	string	The link to the deployed artifact within the 3rd party system.	optional
configuration	string	The ID or the name of the configuration that has been changed by the event.	optional
customProperties	object	The set of any properties related to the event, in the "key" : "value" format.	optional
deploymentName	string	The ID of the triggered deployment.	optional
deploymentProject	string	The project name of the deployed package.	optional
deploymentVersion	string	The version of the triggered deployment.	optional
description	string	The textual description of the configuration change.	optional
end	integer	The end timestamp of the event, in UTC milliseconds. If not set, the current time is used for information-only events. Not applicable to problem-opening events. Such an event stays open until it times out depending on the timeoutMinutes parameter.	optional
eventType	string	The type of the event. `AVAILABILITY_EVENT` `CUSTOM_ALERT` `CUSTOM_ANNOTATION` `CUSTOM_CONFIGURATION` `CUSTOM_DEPLOYMENT` `CUSTOM_INFO` `ERROR_EVENT` `MARKED_FOR_TERMINATION` `PERFORMANCE_EVENT` `RESOURCE_CONTENTION`	required
original	string	The previous value of the configuration.	optional
remediationAction	string	The link to the deployment related remediation action within the external tool.	optional
source	string	The name or ID of the external source of the event.	required
start	integer	The start timestamp of the event, in UTC milliseconds. If not set, the current timestamp is used. You can report information-only events up to 30 days into the past. You can report problem-opening events up to 60 minutes into the past.	optional
timeoutMinutes	integer	The timeout for problem-opening events in minutes. Not applicable to information-only events. If not set, 15 minutes is used. The maximum allowed value is 120 minutes. You can refresh the event by sending the same payload again.	optional
timeseriesIds	string[]	A list of timeseries IDs, related to the event.	optional
title	string	The title of the configuration that has been set by the event.	optional

The `PushEventAttachRules` object

The set of rules defining Dynatrace entities to be associated with the event.

You can specify tags to dynamically match Dynatrace entities or IDs of specific entities.

At least one entity ID or tag is required.

Element	Type	Description	Required
entityIds	string[]	A list of entity IDs to which the event should be attached.	optional
tagRule	TagMatchRule[]	A set of matching rules to dynamically pick up entities based on tags. Only entities seen within the last 24 hours are taken into account for tag-based matching rules.	optional

Element

Type

Description

Required

entityIds

string[]

A list of entity IDs to which the event should be attached.

optional

tagRule

TagMatchRule[]

A set of matching rules to dynamically pick up entities based on tags.

Only entities seen within the last 24 hours are taken into account for tag-based matching rules.

optional

The `TagMatchRule` object

The list of tags to be used for matching Dynatrace entities.

Element Type Description Required

meTypes

string[]

Element	Type	Description	Required
meTypes	string[]	The list of types of the Dynatrace entities (for example hosts or services) you want to pick up by matching. `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`	required
tags	TagInfo[]	The list of tags you want to use for matching. At least one tag is required. You can use custom tags from the UI, imported tags, and tags based on environment variables.	required

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

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

required

The `TagInfo` object

Tag of a Dynatrace entity.

Element Type Description Required

context

string

Element	Type	Description	Required
context	string	The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the `CONTEXTLESS` value. `AWS` `AWS_GENERIC` `AZURE` `CLOUD_FOUNDRY` `CONTEXTLESS` `ENVIRONMENT` `GOOGLE_CLOUD` `KUBERNETES`	required
key	string	The key of the tag. Custom tags have the tag value here.	required
value	string	The value of the tag. Not applicable to custom tags.	optional

The origin of the tag, such as AWS or Cloud Foundry.

Custom tags use the CONTEXTLESS value.

AWS
AWS_GENERIC
AZURE
CLOUD_FOUNDRY
CONTEXTLESS
ENVIRONMENT
GOOGLE_CLOUD
KUBERNETES

required

key

string

The key of the tag.

Custom tags have the tag value here.

required

value

string

The value of the tag.

Not applicable to custom tags.

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.

1{
2  "annotationDescription": "The coffee machine is broken",
3  "annotationType": "defect",
4  "attachRules": {
5    "entityIds": [
6      "CUSTOM_DEVICE-0000000000000007"
7    ],
8    "tagRule": [
9      {
10        "meTypes": [
11          "HOST"
12        ],
13        "tags": [
14          {
15            "context": "CONTEXTLESS",
16            "key": "customTag"
17          }
18        ]
19      }
20    ]
21  },
22  "end": 1521542929000,
23  "eventType": "CUSTOM_ANNOTATION",
24  "source": "OpsControl",
25  "start": 1521042929000
26}

Parameters mapping

	Availability event	Custom annotation	Custom config	Custom deployment	Custom info	Error event	Performance event	Resource contention	Marked for termination
description	req	opt	req	n/a	req	req	req	req	req
title	req	n/a	n/a	n/a	opt	req	req	req	opt
source	req	req	req	req	req	req	req	req	req
annotationType	n/a	req	n/a	n/a	n/a	n/a	n/a	n/a	n/a
annotationDescription	n/a	req	n/a	n/a	n/a	n/a	n/a	n/a	n/a
deploymentName	n/a	n/a	n/a	req	n/a	n/a	n/a	n/a	n/a
deploymentVersion	n/a	n/a	n/a	req	n/a	n/a	n/a	n/a	n/a
deploymentProject	n/a	n/a	n/a	opt	n/a	n/a	n/a	n/a	n/a
ciBackLink	n/a	n/a	n/a	opt	n/a	n/a	n/a	n/a	opt
remediationAction	n/a	n/a	n/a	opt	n/a	n/a	n/a	n/a	n/a
original	n/a	n/a	opt	n/a	n/a	n/a	n/a	n/a	n/a
configuration	n/a	n/a	req	n/a	n/a	n/a	n/a	n/a	n/a
customProperties	opt	opt	opt	opt	opt	opt	opt	opt	opt

Response

Response codes

Code	Type	Description
200	EventStoreResult	Success

Response body objects

The `EventStoreResult` object

Contains IDs of all custom events, created by an event push call.

Element	Type	Description
storedCorrelationIds	string[]	List of correlation IDs for problem-opening-events.
storedEventIds	integer[]	List of event IDs for information-only-events. This field is provided for compatibility reasons. You should use the values from the storedIds field instead.
storedIds	string[]	List of encoded event IDs for information-only-events.

Element

Type

Description

storedCorrelationIds

string[]

List of correlation IDs for problem-opening-events.

storedEventIds

integer[]

List of event IDs for information-only-events.

This field is provided for compatibility reasons. You should use the values from the storedIds field instead.

storedIds

string[]

List of encoded event IDs for information-only-events.

Response body JSON model

1{
2  "storedCorrelationIds": [
3    "string"
4  ],
5  "storedEventIds": [
6    1
7  ],
8  "storedIds": [
9    "string"
10  ]
11}

Example

In this example, the request pushes the CUSTOM_ANNOTATION event, which applies to all custom devices with the Coffee-2nd-floor tag. This annotation is a notification that these coffee machines are broken.

The API token is passed in the Authorization header.

Curl

1curl -X POST \
2  https://mySampleEnv.live.dynatrace.com/api/v1/events \
3  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
4  -H 'Content-Type: application/json' \
5  -d '{
6  "eventType": "CUSTOM_ANNOTATION",
7  "timeoutMinutes": 0,
8  "attachRules": {
9
10    "tagRule": [
11      {
12        "meTypes": [
13          "CUSTOM_DEVICE"
14        ],
15        "tags": [
16          {
17            "context": "CONTEXTLESS",
18            "key": "IG-test"
19          }
20        ]
21      }
22    ]
23  },
24  "source": "OpsControl",
25  "annotationType": "defect",
26  "annotationDescription": "coffee machine is defective"
27}'

Request URL

1https://mySampleEnv.live.dynatrace.com/api/v1/events

Request body

1{
2  "eventType": "CUSTOM_ANNOTATION",
3  "timeoutMinutes": 0,
4  "attachRules": {
5    "tagRule": [
6      {
7        "meTypes": ["CUSTOM_DEVICE"],
8        "tags": [
9          {
10            "context": "CONTEXTLESS",
11            "key": "IG-test"
12          }
13        ]
14      }
15    ]
16  },
17  "source": "OpsControl",
18  "annotationType": "defect",
19  "annotationDescription": "coffee machine is defective"
20}

Response body

1{
2  "storedEventIds": [
3    -6153476110846051426
4  ],
5  "storedIds": [
6    "-6153476110846051426_1533300519291"
7  ],
8  "storedCorrelationIds": []
9}

Response code

200

Events API v1 - POST an event

Authentication

Parameters

Request body objects

The EventCreation object

The PushEventAttachRules object

The TagMatchRule object

The TagInfo object

Request body JSON model

Parameters mapping

Response

Response codes

Response body objects

The EventStoreResult object

Response body JSON model

Example

Curl

Request URL

Request body

Response body

Response code

Related topics

The `EventCreation` object

The `PushEventAttachRules` object

The `TagMatchRule` object

The `TagInfo` object

The `EventStoreResult` object