Events
Security Monitoring is now available Security Monitoring is now available

Events

The events service allows you to programmatically post events to the event stream and fetch events from the event stream. Events are limited to 4000 characters. If an event is sent out with a message containing more than 4000 characters only the 4000 first characters are displayed.

Get an event

get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/events/{event_id}

Overview

This endpoint allows you to query for event details.

Note: If the event you’re querying contains markdown formatting of any kind, you may see characters such as %,\,n in your output.

Arguments

Path Parameters

Name

Type

Description

event_id [required]

integer

The ID of the event.

Response

OK

Object containing an event response.

Expand All

Field

Type

Description

event

object

Object representing an event.

aggregation_key

string

An arbitrary string to use for aggregation. Limited to 100 characters. If you specify a key, all events using that key are grouped together in the Event Stream.

alert_type

enum

If an alert event is enabled, set its type. For example, error, warning, info, and success. Allowed enum values: error,warning,info,success

date_happened

int64

POSIX timestamp of the event. Must be sent as an integer (i.e. no quotes). Limited to events no older than 1 year, 24 days (389 days).

device_name

[string]

A list of device names to post the event with.

host

string

Host name to associate with the event. Any tags associated with the host are also applied to this event.

id

int64

Integer ID of the event.

payload

string

Payload of the event.

priority

enum

The priority of the event. For example, normal or low. Allowed enum values: normal,low

related_event_id

int64

ID of the parent event. Must be sent as an integer (i.e. no quotes).

source_type_name

string

The type of event being posted. Option examples include nagios, hudson, jenkins, my_apps, chef, puppet, git, bitbucket, etc. A complete list of source attribute values available here.

tags

[string]

A list of tags to apply to the event.

text [required]

string

The body of the event. Limited to 4000 characters. The text supports markdown. Use msg_text with the Datadog Ruby library.

title [required]

string

The event title. Limited to 100 characters. Use msg_title with the Datadog Ruby library.

url

string

URL of the event.

status

string

A status.

{
  "event": {
    "aggregation_key": "string",
    "alert_type": "info",
    "date_happened": "integer",
    "device_name": [],
    "host": "string",
    "id": "integer",
    "payload": "{}",
    "priority": "normal",
    "related_event_id": "integer",
    "source_type_name": "string",
    "tags": [
      "environment:test"
    ],
    "text": "Oh boy!",
    "title": "Did you hear the news today?",
    "url": "string"
  },
  "status": "string"
}

Authentication Error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Item Not Found

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Path parameters
export event_id="CHANGE_ME"
# Curl command curl -X get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/events/${event_id} \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

api.Event.get(2603387619536318140)
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

event_id = '1375909614428331251'
dog.get_event(event_id)

Post an event

post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/events

Overview

This endpoint allows you to post events to the stream. Tag them, set priority and event aggregate them with other events.

Request

Body Data (required)

Event request object

Expand All

Field

Type

Description

aggregation_key

string

An arbitrary string to use for aggregation. Limited to 100 characters. If you specify a key, all events using that key are grouped together in the Event Stream.

alert_type

enum

If an alert event is enabled, set its type. For example, error, warning, info, and success. Allowed enum values: error,warning,info,success

date_happened

int64

POSIX timestamp of the event. Must be sent as an integer (i.e. no quotes). Limited to events no older than 1 year, 24 days (389 days).

device_name

[string]

A list of device names to post the event with.

host

string

Host name to associate with the event. Any tags associated with the host are also applied to this event.

id

int64

Integer ID of the event.

payload

string

Payload of the event.

priority

enum

The priority of the event. For example, normal or low. Allowed enum values: normal,low

related_event_id

int64

ID of the parent event. Must be sent as an integer (i.e. no quotes).

source_type_name

string

The type of event being posted. Option examples include nagios, hudson, jenkins, my_apps, chef, puppet, git, bitbucket, etc. A complete list of source attribute values available here.

tags

[string]

A list of tags to apply to the event.

text [required]

string

The body of the event. Limited to 4000 characters. The text supports markdown. Use msg_text with the Datadog Ruby library.

title [required]

string

The event title. Limited to 100 characters. Use msg_title with the Datadog Ruby library.

url

string

URL of the event.

{
  "aggregation_key": "string",
  "alert_type": "info",
  "date_happened": "integer",
  "device_name": [],
  "host": "string",
  "priority": "normal",
  "related_event_id": "integer",
  "source_type_name": "string",
  "tags": [
    "environment:test"
  ],
  "text": "Oh boy!",
  "title": "Did you hear the news today?"
}

Response

OK

Object containing an event response.

Expand All

Field

Type

Description

event

object

Object representing an event.

aggregation_key

string

An arbitrary string to use for aggregation. Limited to 100 characters. If you specify a key, all events using that key are grouped together in the Event Stream.

alert_type

enum

If an alert event is enabled, set its type. For example, error, warning, info, and success. Allowed enum values: error,warning,info,success

date_happened

int64

POSIX timestamp of the event. Must be sent as an integer (i.e. no quotes). Limited to events no older than 1 year, 24 days (389 days).

device_name

[string]

A list of device names to post the event with.

host

string

Host name to associate with the event. Any tags associated with the host are also applied to this event.

id

int64

Integer ID of the event.

payload

string

Payload of the event.

priority

enum

The priority of the event. For example, normal or low. Allowed enum values: normal,low

related_event_id

int64

ID of the parent event. Must be sent as an integer (i.e. no quotes).

source_type_name

string

The type of event being posted. Option examples include nagios, hudson, jenkins, my_apps, chef, puppet, git, bitbucket, etc. A complete list of source attribute values available here.

tags

[string]

A list of tags to apply to the event.

text [required]

string

The body of the event. Limited to 4000 characters. The text supports markdown. Use msg_text with the Datadog Ruby library.

title [required]

string

The event title. Limited to 100 characters. Use msg_title with the Datadog Ruby library.

url

string

URL of the event.

status

string

A status.

{
  "event": {
    "aggregation_key": "string",
    "alert_type": "info",
    "date_happened": "integer",
    "device_name": [],
    "host": "string",
    "id": "integer",
    "payload": "{}",
    "priority": "normal",
    "related_event_id": "integer",
    "source_type_name": "string",
    "tags": [
      "environment:test"
    ],
    "text": "Oh boy!",
    "title": "Did you hear the news today?",
    "url": "string"
  },
  "status": "string"
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Curl command
curl -X post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/events?api_key=${DD_CLIENT_API_KEY} \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "text": "Oh boy!",
  "title": "Did you hear the news today?"
}
EOF

                                        
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

title = "Something big happened!"
text = 'And let me tell you all about it here!'
tags = ['version:1', 'application:web']

api.Event.create(title=title, text=text, tags=tags)

# If you are programmatically adding a comment to this new event
# you might want to insert a pause of .5 - 1 second to allow the
# event to be available.
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

# submitting events doesn 't require an application_key,
# so we don't bother setting it
dog = Dogapi::Client.new(api_key)

dog.emit_event(Dogapi::Event.new('msg_text', :msg_title => 'Title'))

# If you are programmatically adding a comment to this new event
# you might want to insert a pause of.5 - 1 second to allow the
# event to be available.

Query the event stream

get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/events

Overview

The event stream can be queried and filtered by time, priority, sources and tags.

Note: If the event you’re querying contains markdown formatting of any kind, you may see characters such as %,\,n in your output.

Arguments

Query Strings

Name

Type

Description

start [required]

integer

POSIX timestamp.

end [required]

integer

POSIX timestamp.

priority

string

Priority of your events, either low or normal.

sources [required]

string

A comma separated string of sources.

tags

string

A comma separated list indicating what tags, if any, should be used to filter the list of monitors by scope.

unaggregated

boolean

Set unaggregated to true to return all events within the specified [start,end] timeframe. Otherwise if an event is aggregated to a parent event with a timestamp outside of the timeframe, it won’t be available in the output.

Response

OK

An event list response.

Expand All

Field

Type

Description

events

[object]

An array of events.

aggregation_key

string

An arbitrary string to use for aggregation. Limited to 100 characters. If you specify a key, all events using that key are grouped together in the Event Stream.

alert_type

enum

If an alert event is enabled, set its type. For example, error, warning, info, and success. Allowed enum values: error,warning,info,success

date_happened

int64

POSIX timestamp of the event. Must be sent as an integer (i.e. no quotes). Limited to events no older than 1 year, 24 days (389 days).

device_name

[string]

A list of device names to post the event with.

host

string

Host name to associate with the event. Any tags associated with the host are also applied to this event.

id

int64

Integer ID of the event.

payload

string

Payload of the event.

priority

enum

The priority of the event. For example, normal or low. Allowed enum values: normal,low

related_event_id

int64

ID of the parent event. Must be sent as an integer (i.e. no quotes).

source_type_name

string

The type of event being posted. Option examples include nagios, hudson, jenkins, my_apps, chef, puppet, git, bitbucket, etc. A complete list of source attribute values available here.

tags

[string]

A list of tags to apply to the event.

text [required]

string

The body of the event. Limited to 4000 characters. The text supports markdown. Use msg_text with the Datadog Ruby library.

title [required]

string

The event title. Limited to 100 characters. Use msg_title with the Datadog Ruby library.

url

string

URL of the event.

status

string

A status.

{
  "events": [
    {
      "aggregation_key": "string",
      "alert_type": "info",
      "date_happened": "integer",
      "device_name": [],
      "host": "string",
      "id": "integer",
      "payload": "{}",
      "priority": "normal",
      "related_event_id": "integer",
      "source_type_name": "string",
      "tags": [
        "environment:test"
      ],
      "text": "Oh boy!",
      "title": "Did you hear the news today?",
      "url": "string"
    }
  ],
  "status": "string"
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Authentication Error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Required query arguments
export start="CHANGE_ME"
export end="CHANGE_ME"
# Curl command curl -X get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/events?start=${start}?end=${end} \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"
from datadog import initialize, api
import time

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

end_time = time.time()
start_time = end_time - 100

api.Event.query(
    start=start_time,
    end=end_time,
    priority="normal",
    tags=["-env:dev,application:web"],
    unaggregated=True
)
require 'rubygems'
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

end_time = Time.now.to_i
start_time = end_time - 100

dog.stream(start_time, end_time, :priority => "normal", :tags => ["-env:dev,application:web"], :unaggregated => true)