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 ActiveGate | https://{your-activegate-domain}/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 | Event | 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 |
---|---|---|---|
eventType | string | The type of the event. | required |
title | string | The title of the event. | required |
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 |
endTime | integer | The end time of the event, in UTC milliseconds. If not set, the start time plus timeout is used. | 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 |
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 ( | optional |
properties | object | A map of event properties. Keys with prefix Values of Dynatrace-reserved properties must fulfill the requirements of the respective property. | 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.
{
"eventType": "AVAILABILITY_EVENT",
"title": "string",
"startTime": 1,
"endTime": 1,
"timeout": 1,
"entitySelector": "string",
"properties": {}
}
Response
Response codes
Code | Type | Description |
---|---|---|
201 | Event | 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 |
---|---|---|
reportCount | integer | The number of created event reports. |
eventIngestResults | Event | The result of each created event report. |
The EventIngestResult
object
The result of a created event report.
Element | Type | Description |
---|---|---|
status | string | The status of the ingestion. |
correlationId | string | The correlation ID of the created event. |
Response body JSON model
{
"reportCount": 1,
"eventIngestResults": [
{
"status": "INVALID_ENTITY_TYPE",
"correlationId": "string"
}
]
}
Examples
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
curl --request POST \
--url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
--header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
--data '{
"eventType": "MARKED_FOR_TERMINATION",
"title": "Planned host downscale",
"entitySelector": "type(HOST),fromRelationship.isInstanceOf(type(HOST_GROUP),entityName(cloud-burst-hosts))",
"properties": {
"job.number": "21234346"
}
}'
Request URL
https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest
Request body
{
"eventType": "MARKED_FOR_TERMINATION",
"title": "Planned host downscale",
"entitySelector": "type(HOST),fromRelationship.isInstanceOf(type(HOST_GROUP),entityName(cloud-burst-hosts))",
"properties": {
"job.number": "21234346"
}
}
Response body
{
"reportCount": 2,
"eventIngestResults": [
{
"correlationId": "41f5d263011a6c9a",
"status": "OK"
},
{
"correlationId": "80eae4d163cc5760",
"status": "OK"
}
]
}
Response code
201
In this example, the request sends a Custom info event to the BookingService service, marking it as a target of a load test.
The API token is passed in the Authorization header.
Curl
curl --request POST \
--url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
--header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
--data '{
"eventType": "CUSTOM_INFO",
"title": "Loadtest start",
"timeout": 30,
"entitySelector": "type(SERVICE),entityName.equals(BookingService)",
"properties": {
"Tool": "MyLoadTool",
"Load per minute": "100",
"Load pattern": "production"
}
}'
Request URL
https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest
Request body
{
"eventType": "CUSTOM_INFO",
"title": "Loadtest start",
"timeout": 30,
"entitySelector": "type(SERVICE),entityName.equals(BookingService)",
"properties": {
"Tool": "MyLoadTool",
"Load per minute": "100",
"Load pattern": "production"
}
}
Response body
{
"reportCount": 1,
"eventIngestResults": [
{
"correlationId": "eba82f647696e485",
"status": "OK"
}
]
}
Response code
201
In this example, the request sends an Error event to the BookingService service, indicating a failed update. The allowDavisMerge property is set to false
, preventing Davis from merging this event with any other event.
The API token is passed in the Authorization header.
Curl
curl --request POST \
--url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
--header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
--data '{
"eventType": "ERROR_EVENT",
"title": "Product catalog update failed",
"timeout": 30,
"entitySelector": "type(SERVICE),entityName.equals(BookingService)",
"properties": {
"allowDavisMerge": "false",
"Catalog": "APAC travels",
"Batch processor": "travel-catalog"
}
}'
Request URL
https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest
Request body
{
"eventType": "ERROR_EVENT",
"title": "Product catalog update failed",
"timeout": 30,
"entitySelector": "type(SERVICE),entityName.equals(BookingService)",
"properties": {
"allowDavisMerge": "false",
"Catalog": "APAC travels",
"Batch processor": "travel-catalog"
}
}
Response body
{
"reportCount": 1,
"eventIngestResults": [
{
"correlationId": "cefb7ae03ac720b6",
"status": "OK"
}
]
}
Response code
201