Events API v2 - POST an event

Ingests a custom event to Dynatrace.

The request consumes an application/json payload.

The ingestion of custom events consumes Davis Data Units (DDUs) from the events pool.

POST	ManagedDynatrace for Government	`https://{your-domain}/e/{your-environment-id}/api/v2/events/ingest`
	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v2/events/ingest`
	Environment and Cluster ActiveGate (default port 9999)	`https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/events/ingest`

Authentication

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

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

Parameters

Parameter	Type	Description	In	Required
body	EventIngest	The JSON body of the request. Contains properties of the new event.	body	optional

Request body objects

The `EventIngest` object

The configuration of an event to be ingested.

Element	Type	Description	Required
endTime	integer	The end time of the event, in UTC milliseconds. If not set, the start time plus timeout is used.	optional
entitySelector	string	The entity selector, defining a set of Dynatrace entities to be associated with the event. Only entities that have been active within the last 24 hours can be selected. If not set, the event is associated with the environment (`dt.entity.environment`) entity.	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_EVENT`	required
properties	object	A map of event properties. Keys with prefix `dt.` are generally disallowed, with the exceptions of `dt.event.`, `dt.davis.` and `dt.entity.`. These reserved keys may be used to set event properties with predefined semantics within the Dynatrace product. `dt.entity.*` keys may be used to provide additional information on an event, but will not lead to the event being tied to the specified entities. All other keys are interpreted as user-defined event properties. Values of Dynatrace-reserved properties must fulfill the requirements of the respective property.	optional
startTime	integer	The start time of the event, in UTC milliseconds. If not set, the current timestamp is used. Depending on the event type, the start time must not lie in the future more than 5 minutes for trigger events and 7 days for info events.	optional
timeout	integer	The timeout of the event, in minutes. If not set, 15 is used. The timeout will automatically be capped to a maximum of 360 minutes (6 hours). Problem-opening events can be refreshed and therefore kept open by sending the same payload again.	optional
title	string	The title of the event.	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.

1{
2  "endTime": 1,
3  "entitySelector": "string",
4  "eventType": "AVAILABILITY_EVENT",
5  "properties": {},
6  "startTime": 1,
7  "timeout": 1,
8  "title": "string"
9}

Response

Response codes

Code	Type	Description
201	EventIngestResults	The event ingest request was received by the server. The response body indicates for each event whether its creation was successful.

Response body objects

The `EventIngestResults` object

The results of an event ingest.

Element	Type	Description
eventIngestResults	EventIngestResult[]	The result of each created event report.
reportCount	integer	The number of created event reports.

The `EventIngestResult` object

The result of a created event report.

Element	Type	Description
correlationId	string	The correlation ID of the created event.
status	string	The status of the ingestion. `INVALID_ENTITY_TYPE` `INVALID_METADATA` `INVALID_TIMESTAMPS` `OK`

Response body JSON model

1{
2  "eventIngestResults": [
3    {
4      "correlationId": "string",
5      "status": "INVALID_ENTITY_TYPE"
6    }
7  ],
8  "reportCount": 1
9}

Examples

An operations team wants to push a Marked for termination event to all the hosts that are planned to be removed. They also want to include the purpose for the deletion and a job identifier. The hosts to be removed are gathered in a designated host group.

In this example, the request sends a Marked for termination event to hosts that are planned to be removed. Such hosts are identified by the cloud-burst-hosts host group. The event automatically applies to all hosts that are part of the group. The purpose for termination and automation job number are provided as additional information.

The API token is passed in the Authorization header.

Curl

1curl --request POST \
2  --url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
3  --header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "eventType": "MARKED_FOR_TERMINATION",
7    "title": "Planned host downscale",
8    "entitySelector": "type(HOST),fromRelationship.isInstanceOf(type(HOST_GROUP),entityName(cloud-burst-hosts))",
9    "properties": {
10        "job.number": "21234346"
11    }
12}'

Request URL

1https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest

Request body

1{
2    "eventType": "MARKED_FOR_TERMINATION",
3    "title": "Planned host downscale",
4    "entitySelector": "type(HOST),fromRelationship.isInstanceOf(type(HOST_GROUP),entityName(cloud-burst-hosts))",
5    "properties": {
6        "job.number": "21234346"
7    }
8}

Response body

1{
2  "reportCount": 2,
3  "eventIngestResults": [
4    {
5      "correlationId": "41f5d263011a6c9a",
6      "status": "OK"
7    },
8    {
9      "correlationId": "80eae4d163cc5760",
10      "status": "OK"
11    }
12  ]
13}

Response code

201