API Reference

Overview

This section details Datadog's HTTP API. It makes it easy to get data in and out of Datadog. The Datadog API uses resource-oriented URLs, uses status codes to indicate the success or failure of requests and returns JSON from all requests. Let's dive in and see how it works.
Libraries
There are many client libraries that wrap the Datadog API. Check them out.
API Endpoint
https://app.datadoghq.com/api/

Authentication

All requests to Datadog's API must be authenticated. Requests that write data require reporting access and require an API key. Requests that read data require full access and also require an application key.

You can manage your account's API and application keys here.

Example
curl "https://app.datadoghq.com/api/v1/validate?api_key=MY_API_KEY"
from dogapi import dog_http_api as api

api.api_key = 'api_key'
api.application_key = 'app_key'
require 'rubygems'
require 'dogapi'

dog = Dogapi::Client.new('api_key', 'application_key')

Success and Errors

The Datadog API uses HTTP status codes to indicate the success or failure of a request.

An error indicates that the service did not successfully handle your request. In addition to the status code, the response may contain a JSON object with an errors array containing more detailed error messages.

If the service is able to handle your request, but some issues are present (e.g. using a deprecated API or API version), the HTTP status code will indicate success and the response body will contain the expected result with the addition of a warnings array containing detailed warning messages.

Status Codes
  • 200 OK
  • 201 Created
  • 202 Accepted
  • 204 No Content
  • 301 Moved Permanently
  • 304 Not Modified
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 422 Unprocessable Entity
  • 500 Server Error
Example Error Response
{ 'errors': [
    'Something bad happened to the server.',
    'Your query made the server very sad.'
  ]
}
Example Warning Response
{ 'some_thing': ...,
  'some_other_thing': ...,
  'warnings': [
      'This is a deprecated API.'
  ]
}

Metrics

The metrics end-point allows you to post metrics data so it can be graphed on Datadog's dashboards.

Post time series points

The metrics end-point allows you to post time-series data that can be graphed on Datadog's dashboards.

Arguments
  • series [required]
    A JSON array of metrics of the form. Each metric is of the form:
    • metric [required]
      The name of the time series
    • points [required]
      A JSON array of points. Each point is of the form:
      [[POSIX_timestamp, numeric_value], ...]
      Note that the timestamp must be current.
    • host [optional, default=None]
      The name of the host that produced the metric.
    • tags [optional, default=None]
      A list of tags associated with the metric.
    • metric_type [optional, default=gauge]
      The type of the metric - gauge or counter (counter data is expected as a rate). Gauges are 32bit floats while counters are 64bit integers.
Signature
POST https://app.datadoghq.com/api/v1/series
Example Request
from dogapi import dog_http_api as api

api.api_key = 'apikey_3'
api.application_key = '9d945c35fd7cc7abb1088fd0632ef8e25516af74'

# Submit a single point with a timestamp of `now`
api.metric('page.views', 1000)

# Submit a point with a timestamp (must be ~current)
api.metric('my.pair', (1317652676, 15))

# Submit multiple points.
api.metric('my.series', [(1317652676, 15), (1317652800, 16)])

# Submit a point with a host and tags.
api.metric('my.series', 100, host="myhost.example.com", tags=["version:1"])
curl  -X POST -H "Content-type: application/json" \
-d '{ "series" :
         [{"metric":"test.metric",
          "points":[[1346340794, 20]],
          "type":"gauge",
          "host":"test.example.com",
          "tags":["environment:test"]}
        ]
    }' \
'https://app.datadoghq.com/api/v1/series?api_key=9775a026f1ca7d1c6c5af9d94d9595a4'
require 'rubygems'
require 'dogapi'

api_key = "abcdef123456"

dog = Dogapi::Client.new(api_key)

# Submit one metric value.
dog.emit_point('some.metric.name', 50.0, :host => "my_host.example.com")

# Submit multiple metric values
points = [[Time.now, 0], [Time.now + 10, 10.0], [Time.now + 20, 20.0]]
dog.emit_points('some.metric.name', points, :tags => ["version:1"])

Events

The events service allows you to programatically post events to the stream and fetch events from the stream.

Post an Event

This end point allows you to post events to the stream. You can tag them, set priority and event aggregate them with other events.

Arguments
  • title [required]
    The event title. Limited to 100 characters.
  • text [required]
    The body of the event. Limited to 4000 characters.
  • date_happened [optional, default=now]
    POSIX timestamp of the event.
  • priority [optional, default='normal']
    The priority of the event ('normal' or 'low').
  • host [optional, default=None]
    Host name to associate with the event.
  • tags [optional, default=None]
    A list of tags to apply to the event.
  • alert_type [optional, default='info']
    "error", "warning", "info" or "success".
  • aggregation_key [optional, default=None]
    An arbitrary string to use for aggregation, max length of 100 characters.
  • source_type_name [optional, default=None]
    The type of event being posted.
    Options: nagios, hudson, jenkins, user, my apps, feed, chef, puppet, git, bitbucket, fabric, capistrano
Signature
POST /api/v1/events
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# All optional parameters are specified as keyword arguments.
api.event_with_response(title, text, tags=tags)
curl  -X POST -H "Content-type: application/json" \
-d '{
      "title": "Did you hear the news today?",
      "text": "Oh boy!",
      "priority": "normal",
      "tags": ["environment:test"],
      "alert_type": "info"
  }' \
'https://app.datadoghq.com/api/v1/events?api_key=9775a026f1ca7d1c6c5af9d94d9595a4'
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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'))
Example Response
1378859520391900319
{
    "event": {
        "date_happened": 1346449298, 
        "handle": null, 
        "id": 1378859526682864843, 
        "priority": "normal", 
        "related_event_id": null, 
        "tags": [
            "environment:test"
        ], 
        "text": null, 
        "title": "Did you hear the news today?", 
        "url": "https://app.datadoghq.com/event/jump_to?event_id=1378859526682864843"
    }, 
    "status": "ok"
}
["202",
 {"status"=>"ok",
  "event"=>
   {"priority"=>"normal",
    "date_happened"=>1346452418,
    "title"=>"Title",
    "url"=>
     "https://app.datadoghq.com/event/jump_to?event_id=1378911893708573827",
    "text"=>"msg_text",
    "tags"=>[],
    "related_event_id"=>nil,
    "id"=>1378911893708573827}}]

Get an Event

This end point allows you to query for event details.

Arguments
This end point takes no JSON arguments.
Signature
GET /api/v1/events/:event_id
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

event_id = '1375909614428331251'

api.get_event(event_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
event_id=1377281704830403917

curl "https://app.datadoghq.com/api/v1/events/${event_id}?api_key=${api_key}&application_key=${app_key}"
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

event_id = '1375909614428331251'
dog.get_event(event_id)
Example Response
{'alert_type': 'info',
 'date_happened': 1346273469,
 'device_name': None,
 'host': None,
 'id': 1375909614428331251,
 'payload': '{}',
 'priority': 'normal',
 'resource': '/api/v1/events/1375909614428331251',
 'tags': ['application:web', 'version:1'],
 'text': 'And let me tell you all about it here!',
 'title': 'Something big happened!',
 'url': '/event/jump_to?event_id=1375909614428331251'}
{
    "event": {
        "alert_type": "info", 
        "date_happened": 1346355252, 
        "device_name": null, 
        "host": null, 
        "id": 1377281704830403917, 
        "payload": "{}", 
        "priority": "normal", 
        "resource": "/api/v1/events/1377281704830403917", 
        "tags": [
            "environment:test"
        ], 
        "text": "Oh boy!", 
        "title": "Did you hear the news today?", 
        "url": "/event/jump_to?event_id=1377281704830403917"
    }
}
["200",
 {"event"=>
   {"date_happened"=>1346273469,
    "alert_type"=>"info",
    "resource"=>"/api/v1/events/1375909614428331251",
    "title"=>"Something big happened!",
    "url"=>"/event/jump_to?event_id=1375909614428331251",
    "text"=>"And let me tell you all about it here!",
    "tags"=>["application:web", "version:1"],
    "id"=>1375909614428331251,
    "priority"=>"normal",
    "host"=>nil,
    "device_name"=>nil,
    "payload"=>"{}"}}]

Query the Event Stream

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

Arguments
  • start [required]
    POSIX timestamp
  • end [required]
    POSIX timestamp
  • priority [optional, default=None]
    'low' or 'normal'
  • sources [optional, default=None]
    A comma separated list of sources
  • tags [optional, default=None]
    A comma separated list of tags
Signature
GET /api/v1/events
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'


start_time = 1346272158
end_time = 1346274158

api.stream(start_time, end_time, priority="normal", tags=["application:web"])
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

start_time = 1346272158
end_time = 1346274158

dog.stream(start_time, end_time, :priority=>"normal", :tags=>["application:web"])
# Note: this end point only accepts form-encoded requests.

curl -G -H "Content-type: application/json" \
    -d "start=1346272158" \
    -d "end=1346274158" \
    -d "api_key=9775a026f1ca7d1c6c5af9d94d9595a4" \
    -d "application_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" \
    'https://app.datadoghq.com/api/v1/events'
Example Response
[{'alert_type': 'info',
  'comments': [],
  'date_happened': 1346273496,
  'device_name': None,
  'host': None,
  'id': 1375910067732769979,
  'is_aggregate': False,
  'priority': 'normal',
  'resource': '/api/v1/events/1375910067732769979',
  'source': 'My Apps',
  'tags': ['application:web', 'version:1'],
  'text': 'And let me tell you all about it here!',
  'title': 'Something big happened!',
  'url': '/event/jump_to?event_id=1375910067732769979'},
 {'alert_type': 'info',
  'comments': [],
  'date_happened': 1346273469,
  'device_name': None,
  'host': None,
  'id': 1375909614428331251,
  'is_aggregate': False,
  'priority': 'normal',
  'resource': '/api/v1/events/1375909614428331251',
  'source': 'My Apps',
  'tags': ['application:web', 'version:1'],
  'text': 'And let me tell you all about it here!',
  'title': 'Something big happened!',
  'url': '/event/jump_to?event_id=1375909614428331251'}]
["200", {"events"=>[]}]
{
    "events": [
        {
            "alert_type": "info",
            "comments": [],
            "date_happened": 1346273496,
            "device_name": null,
            "host": null,
            "id": 1375910067732769979,
            "is_aggregate": false,
            "priority": "normal",
            "resource": "/api/v1/events/1375910067732769979",
            "source": "My Apps",
            "tags": [
                "application:web",
                "version:1"
            ],
            "text": "And let me tell you all about it here!",
            "title": "Something big happened!",
            "url": "/event/jump_to?event_id=1375910067732769979"
        },
        {
            "alert_type": "info",
            "comments": [],
            "date_happened": 1346273469,
            "device_name": null,
            "host": null,
            "id": 1375909614428331251,
            "is_aggregate": false,
            "priority": "normal",
            "resource": "/api/v1/events/1375909614428331251",
            "source": "My Apps",
            "tags": [
                "application:web",
                "version:1"
            ],
            "text": "And let me tell you all about it here!",
            "title": "Something big happened!",
            "url": "/event/jump_to?event_id=1375909614428331251"
        }
    ]
}

Service Checks

The service check endpoint allows you to post check statuses for use with monitors.

Post a Check Run

Arguments
  • check [required]
    The text for the message
  • host_name [required]
    The name of the host submitting the check
  • status [required]
    An integer for the status of the check.
    Options: '0': OK, '1': WARNING, '2': CRITICAL, '3': UNKNOWN
  • timestamp [optional, default=now]
    POSIX timestamp of the event.
  • message [optional, default=None]
    A description of why this status ocurred
  • tags [optional, default=None]
    A list of key:val tags for this check
Signature
POST /api/v1/check_run
Example Request
from dogapi import dog_http_api as api
from dogapi.constants import CheckStatus

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

check = 'app.ok'
host = 'app1'
status = CheckStatus.OK

api.service_check(check, host, status, message='Response: 200 OK')
curl  -X POST -H "Content-type: application/json" \
-d '{
      "check": "app.is_ok",
      "host_name": "app1",
      "timestamp": "1416241199",
      "status": 0
  }' \
'https://app.datadoghq.com/api/v1/check_run?api_key=9775a026f1ca7d1c6c5af9d94d9595a4'
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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.service_check('app.is_ok', 'app1', 0, :message => 'Response: 200 OK')
Example Response
{'status': 'ok'}
{
    "status": "ok"
}
["202", {"status"=>"ok"}]

Monitors

Monitors allow you to watch a metric or check that you care about, notifying your team when some defined threshold is exceeded. Please refer to the Guide to Monitoring for more information on creating monitors.

Create a monitor

Arguments
  • type [required]
    The type of the monitor, chosen from:
    • metric alert
    • service check
  • query [required]
    The monitor query to notify on with syntax varying depending on what type of monitor you are creating.
    Metric Alert Query
    time_aggr(window):space_aggr:metric{tags} [by {key}] operator #
    • time_aggr avg, sum, max, or min
    • time_window last_#m (5, 10, 15, or 30), last_#h (1, 2, or 4), or last_1d
    • space_aggr avg, sum, min, or max
    • tags one or more tags (comma-separated), or *
    • key a 'key' in key:value tag syntax; defines a separate alert for each tag in the group (multi-alert)
    • operator <, <=, >, >=, ==, or !=
    • # an integer or decimal number used to set the threshold
    Service Check Query
    "check".over(tags).last(count).count_by_status()
    • check name of the check, e.g. datadog.agent.up
    • tags one or more quoted tags (comma-separated), or "*". e.g.: .over("env:prod", "role:db")
    • count must be at >= your max threshold (defined in the options). e.g. if you want to notify on 1 critical, 3 ok and 2 warn statuses count should be 3.
  • name [optional, default=dynamic, based on query]
    The name of the alert.
  • message [optional, default=dynamic, based on query]
    A message to include with notifications for this monitor. Email notifications can be sent to specific users by using the same '@username' notation as events.
  • options [optional]
    A dictionary of options for the monitor. There are options that are common to all types as well as options that are specific to certain monitor types.
    Common Options
    • silenced dictionary of scopes to timestamps or None. Each scope will be muted until the given POSIX timestamp or forever if the value is None.

      Default: None

      Examples:

      • To mute the alert completely:

        {'*': None}

      • To mute role:db for a short time:

        {'role:db': 1412798116}

    • notify_no_data a boolean indicating whether this monitor will notify when data stops reporting.

      Default: false

    • no_data_timeframe the number of minutes before a monitor will notify when data stops reporting. Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks.

      Default: 2x timeframe for metric alerts, 2 minutes for service checks

    • timeout_h the number of hours of the monitor not reporting data before it will automatically resolve from a triggered state.

      Default: None

    • renotify_interval the number of minutes after the last notification before a monitor will re-notify on the current status. It will only re-notify if it's not resolved.

      Default: None

    • escalation_message a message to include with a re-notification. Supports the '@username' notification we allow elsewhere. Not applicable if renotify_interval is None.

      Default: None

    • notify_audit a boolean indicating whether tagged users will be notified on changes to this monitor.

      Default: False

    Service Check Options
    These options only apply to service checks and will be ignored for other monitor types.
    • thresholds a dictionary of thresholds by status. Because service checks can have multiple thresholds, we don't define them directly in the query.

      Default: {'ok': 1, 'critical': 1, 'warning': 1}

Signature
POST /api/v1/monitor
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Create a new monitor
options = {
    "notify_no_data": True,
    "no_data_timeframe": 20
}
api.monitor("metric alert", "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", "Bytes received on host0", "We may need to add web hosts if this is consistently high.", options=options)
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Create a new monitor
options = {
  'notify_no_data' => true,
  'no_data_timeframe' => 20
}
dog.monitor("metric alert", "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", :name => "Bytes received on host0", :message => "We may need to add web hosts if this is consistently high.", :options => options)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
alert_id=512

curl -X POST -H "Content-type: application/json" \
-d '{
      "type": "metric alert",
      "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
      "name": "Bytes received on host0",
      "message": "We may need to add web hosts if this is consistently high.",
      "options": {
      	"notify_no_data": true,
      	"no_data_timeframe": 20
      }
    }' \
    "https://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}"
Example Response
92088
["200",
 {"name"=>"Bytes received on host0",
  "org_id"=>1499,
  "options"=>
   {"notify_no_data"=>true,
    "no_data_timeframe"=>20,
    "notify_audit"=>false,
    "silenced"=>{}},
  "state"=>{},
  "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "message"=>"We may need to add web hosts if this is consistently high.",
  "type"=>"metric alert",
  "id"=>92089}]
{
    "id": 92090,
    "message": "We may need to add web hosts if this is consistently high.",
    "name": "Bytes received on host0",
    "options": {
        "no_data_timeframe": 20,
        "notify_audit": false,
        "notify_no_data": true,
        "silenced": {}
    },
    "org_id": 1499,
    "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
    "state": {},
    "type": "metric alert"
}

Get a monitor's details

Arguments
  • group_states [optional, default=None]
    A comma-separated string indicating what, if any, group states to include. Choose from one or more from 'all', 'alert', 'warn', or 'no data'. Example: 'alert,warn'
Signature
GET /api/v1/monitor/:monitor_id
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Get a monitor's details
api.get_monitor(91879)
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Get a monitors's details
dog.get_monitor(91879)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
monitor_id=91879

curl -G "https://app.datadoghq.com/api/v1/monitor/${monitor_id}" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"
Example Response
{'id': 91879,
 'message': 'We may need to add web hosts if this is consistently high.',
 'name': 'Bytes received on host0',
 'options': {'notify_audit': False, 'notify_no_data': False, 'silenced': {}},
 'org_id': 1499,
 'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
 'type': 'metric alert'}
["200",
 {"name"=>"Bytes received on host0",
  "org_id"=>1499,
  "options"=>{"notify_no_data"=>false, "notify_audit"=>false, "silenced"=>{}},
  "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "message"=>"We may need to add web hosts if this is consistently high.",
  "type"=>"metric alert",
  "id"=>91879}]
{
    "id": 91879,
    "message": "We may need to add web hosts if this is consistently high.",
    "name": "Bytes received on host0",
    "options": {
        "notify_audit": false,
        "notify_no_data": false,
        "silenced": {}
    },
    "org_id": 1499,
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
    "type": "metric alert"
}

Edit a monitor

Arguments
  • query [required]
    The metric query to alert on.
  • name [optional, default=dynamic, based on query]
    The name of the monitor.
  • message [optional, default=dynamic, based on query]
    A message to include with notifications for this monitor. Email notifications can be sent to specific users by using the same '@username' notation as events.
  • options [optional, default=None]
    Refer to the create monitor documentation for details on the available options.
Signature
PUT /api/v1/monitor/:monitor_id
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Edit an existing monitor
api.update_monitor(91879, "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", "Bytes received on host0", "We may need to add web hosts if this is consistently high.")
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Edit an existing monitor
dog.update_monitor(91879, "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", :message => "Bytes received on host0", :name => "We may need to add web hosts if this is consistently high.")
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
monitor_id=91879

curl -X PUT -H "Content-type: application/json" \
-d '{
      "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "name": "Bytes received on host0",
      "message": "We may need to add web hosts if this is consistently high."
    }' \
    "https://app.datadoghq.com/api/v1/monitor/${monitor_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
91879
["200",
 {"name"=>"We may need to add web hosts if this is consistently high.",
  "org_id"=>1499,
  "options"=>{"notify_no_data"=>false, "notify_audit"=>false, "silenced"=>{}},
  "state"=>{},
  "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "message"=>"Bytes received on host0",
  "type"=>"metric alert",
  "id"=>91879}]
{
    "id": 91879,
    "message": "We may need to add web hosts if this is consistently high.",
    "name": "Bytes received on host0",
    "options": {
        "notify_audit": false,
        "notify_no_data": false,
        "silenced": {}
    },
    "org_id": 1499,
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
    "state": {},
    "type": "metric alert"
}

Delete a monitor

Arguments
This end point takes no JSON arguments.
Signature
DELETE /api/v1/monitor/:monitor_id
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Delete a monitor
api.delete_monitor(57410)
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Delete a monitor
dog.delete_monitor(62625)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
monitor_id=59409

curl -X DELETE "https://app.datadoghq.com/api/v1/monitor/${monitor_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{'deleted_monitor_id': 57410}
["200", {"deleted_monitor_id"=>62625}]
{
    "deleted_monitor_id": 59409
}

Get all monitor details

Arguments
  • group_states [optional, default=None]
    A comma-separated string indicating what, if any, group states to include. Choose from one or more from 'all', 'alert', 'warn', or 'no data'. Example: 'alert,warn'
  • tags [optional, default=None]
    A comma-separated string indicating what tags, if any, should be used to filter the list of monitors by scope
Signature
GET /api/v1/monitor
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Get all monitor details
api.get_all_monitors()
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Get all monitor details
dog.get_all_monitors()
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -G "https://app.datadoghq.com/api/v1/monitor" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"
Example Response
[{'id': 91879,
  'message': 'We may need to add web hosts if this is consistently high.',
  'name': 'Bytes received on host0',
  'options': {'notify_audit': False, 'notify_no_data': False, 'silenced': {}},
  'org_id': 1499,
  'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
  'type': 'metric alert'},
 {'id': 91875,
  'message': u'',
  'name': '**system.net.bytes_rcvd** over **host:host0** was **> 100** on average during the **last 1h**.',
  'options': {'escalation_message': u'',
              'no_data_timeframe': False,
              'notify_audit': True,
              'notify_no_data': False,
              'renotify_interval': None,
              'silenced': {},
              'timeout_h': None},
  'org_id': 1499,
  'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
  'type': 'metric alert'}]
["200",
 [{"name"=>"Bytes received on host0",
   "org_id"=>1499,
   "options"=>{"notify_no_data"=>false, "notify_audit"=>false, "silenced"=>{}},
   "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
   "message"=>"We may need to add web hosts if this is consistently high.",
   "type"=>"metric alert",
   "id"=>91879},
  {"name"=>
    "**system.net.bytes_rcvd** over **host:host0** was **> 100** on average during the **last 1h**.",
   "org_id"=>1499,
   "options"=>
    {"notify_audit"=>true,
     "timeout_h"=>nil,
     "silenced"=>{},
     "no_data_timeframe"=>false,
     "notify_no_data"=>false,
     "renotify_interval"=>nil,
     "escalation_message"=>""},
   "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
   "message"=>"",
   "type"=>"metric alert",
   "id"=>91875}]]
[
    {
        "id": 91879,
        "message": "We may need to add web hosts if this is consistently high.",
        "name": "Bytes received on host0",
        "options": {
            "notify_audit": false,
            "notify_no_data": false,
            "silenced": {}
        },
        "org_id": 1499,
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
        "type": "metric alert"
    },
    {
        "id": 91875,
        "message": "",
        "name": "**system.net.bytes_rcvd** over **host:host0** was **> 100** on average during the **last 1h**.",
        "options": {
            "escalation_message": "",
            "no_data_timeframe": false,
            "notify_audit": true,
            "notify_no_data": false,
            "renotify_interval": null,
            "silenced": {},
            "timeout_h": null
        },
        "org_id": 1499,
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
        "type": "metric alert"
    }
]

Mute all monitors

Muting will prevent all monitors from notifying through email and posts to the event stream. State changes will only be visible by checking the alert page.

Arguments
This end point takes no JSON arguments.
Signature
POST /api/v1/monitor/mute_all
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Mute all monitors
api.mute_monitors()
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Mute all alerts
dog.mute_monitors()
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -X POST "https://app.datadoghq.com/api/v1/monitor/mute_all?api_key=${api_key}&application_key=${app_key}"
Example Response
{'active': True,
 'disabled': False,
 'end': None,
 'id': 1646,
 'scope': ['*'],
 'start': 1412805854}
["200",
 {"end"=>nil,
  "disabled"=>false,
  "start"=>1412805855,
  "active"=>true,
  "scope"=>["*"],
  "id"=>1647}]
{
    "active": true,
    "disabled": false,
    "end": null,
    "id": 1648,
    "scope": [
        "*"
    ],
    "start": 1412805856
}

Unmute all monitors

Arguments
This end point takes no JSON arguments.
Signature
POST /api/v1/monitor/unmute_all
Example Request
from dogapi import dog_http_api as api

api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

# Unmute all alerts
api.unmute_monitors()
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Unmute all alerts
dog.unmute_monitors()
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -X POST "https://app.datadoghq.com/api/v1/monitor/unmute_all?api_key=${api_key}&application_key=${app_key}"
Example Response
This end point does not return JSON on successful requests.

Mute a monitor

Arguments
  • scope [optional, default=None]
    The scope to apply the mute to, e.g. role:db
  • end [optional, default=None]
    A POSIX timestamp for when the mute should end
  • Signature
    POST /api/v1/monitor/:monitor_id/mute
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Mute a monitor
    api.mute_monitor(62628)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Mute a monitor
    dog.mute_monitor(62628)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    monitor_id=62628
    
    curl -X POST "https://app.datadoghq.com/api/v1/monitor/${monitor_id}/mute?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'id': 62628,
     'message': u'',
     'name': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200',
     'options': {'is_data_sparse': False,
                 'notify_audit': True,
                 'notify_no_data': False,
                 'renotify_interval': None,
                 'silenced': {'*': None},
                 'timeout_h': None},
     'org_id': 1499,
     'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200',
     'state': {},
     'type': 'metric alert'}
    ["200",
     {"name"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
      "org_id"=>1499,
      "options"=>
       {"notify_no_data"=>false,
        "notify_audit"=>true,
        "timeout_h"=>nil,
        "silenced"=>{"*"=>nil},
        "is_data_sparse"=>false,
        "renotify_interval"=>nil},
      "state"=>{},
      "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
      "message"=>"",
      "type"=>"metric alert",
      "id"=>62628}]
    {
        "id": 62628,
        "message": "",
        "name": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
        "options": {
            "is_data_sparse": false,
            "notify_audit": true,
            "notify_no_data": false,
            "renotify_interval": null,
            "silenced": {
                "*": null
            },
            "timeout_h": null
        },
        "org_id": 1499,
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
        "state": {},
        "type": "metric alert"
    }
    

    Unmute a monitor

    Arguments
  • scope [optional, default=None]
    The scope to apply the mute to. For example, if your alert is grouped by {host}, you might mute 'host:app1'
  • Signature
    POST /api/v1/monitor/:monitor_id/unmute
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Unmute all alerts
    api.unmute_monitor(62628)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Unmute all alerts
    dog.unmute_monitor(62628)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    monitor_id=62628
    
    curl -X POST "https://app.datadoghq.com/api/v1/monitor/${monitor_id}/mute?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'id': 62628,
     'message': u'',
     'name': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200',
     'options': {'is_data_sparse': False,
                 'notify_audit': True,
                 'notify_no_data': False,
                 'renotify_interval': None,
                 'silenced': {},
                 'timeout_h': None},
     'org_id': 1499,
     'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200',
     'state': {},
     'type': 'metric alert'}
    ["200",
     {"name"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
      "org_id"=>1499,
      "options"=>
       {"notify_no_data"=>false,
        "notify_audit"=>true,
        "timeout_h"=>nil,
        "silenced"=>{},
        "is_data_sparse"=>false,
        "renotify_interval"=>nil},
      "state"=>{},
      "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
      "message"=>"",
      "type"=>"metric alert",
      "id"=>62628}]
    {
        "id": 62628,
        "message": "",
        "name": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
        "options": {
            "is_data_sparse": false,
            "notify_audit": true,
            "notify_no_data": false,
            "renotify_interval": null,
            "silenced": {
                "*": null
            },
            "timeout_h": null
        },
        "org_id": 1499,
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 200",
        "state": {},
        "type": "metric alert"
    }
    

    Schedule monitor downtime

    Arguments
  • scope [required]
    The scope to apply the downtime to, e.g. 'host:app2'
  • start [required]
    POSIX timestamp to start the downtime.
  • end [optional, default=None]
    POSIX timestamp to end the downtime. In the default case, the downtime will go until cancelled.
  • message [optional, default=None]
    A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same '@username' notation as events
  • Signature
    POST /api/v1/downtime
    Example Request
    import time
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Schedule downtime
    api.schedule_downtime('env:staging', int(time.time()))
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Schedule downtime
    dog.schedule_downtime('env:testing', Time.now.to_i)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -X POST -H "Content-type: application/json" \
    -d '{
          "scope": "env:prod",
          "start": 1412809696
        }' \
        "https://app.datadoghq.com/api/v1/downtime?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    1673
    ["200",
     {"end"=>nil,
      "disabled"=>false,
      "start"=>1412859237,
      "active"=>false,
      "scope"=>["env:testing"],
      "id"=>1674}]
    {
        "active": false,
        "disabled": false,
        "end": null,
        "id": 1656,
        "scope": [
            "env:prod"
        ],
        "start": 1412809696
    }
    

    Update monitor downtime

    Arguments
  • scope [optional, default=original scope]
    The scope to apply the downtime to, e.g. 'host:app2'
  • start [optional, default=original start]
    POSIX timestamp to start the downtime
  • end [optional, default=original end]
    POSIX timestamp to end the downtime, or None if the downtime should continue until cancelled
  • message [optional, default=original message]
    A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same '@username' notation as events
  • Signature
    POST /api/v1/downtime
    Example Request
    import time
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Update downtime
    api.update_downtime(4336, 'env:staging', end=int(time.time()) + 60000, message="Doing some testing on staging.")
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Update downtime
    dog.update_downtime(4336, :scope => 'env:testing', :end => Time.now.to_i + 60000, :message => "Doing some testing on staging.")
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    downtime_id=4336
    
    curl -X PUT -H "Content-type: application/json" \
    -d '{
          "scope": "env:staging",
          "message": "Doing some testing on staging"
        }' \
        "https://app.datadoghq.com/api/v1/downtime/${downtime_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    4336
    ["200",
     {"end"=>1418303372,
      "disabled"=>false,
      "start"=>1418224729,
      "active"=>true,
      "scope"=>["env:testing"],
      "message"=>"Doing some testing on staging.",
      "id"=>4336}]
    {
        "active": true, 
        "disabled": false, 
        "end": 1418303372, 
        "id": 4336, 
        "message": "Doing some testing on staging", 
        "scope": [
            "env:staging"
        ], 
        "start": 1418224729
    }
    

    Cancel monitor downtime

    Arguments
    This end point takes no JSON arguments.
    Signature
    DELETE /api/v1/downtime/:downtime_id
    Example Request
    import time
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Cancel downtime
    api.cancel_downtime(1654)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Cancel downtime
    dog.cancel_downtime(1655)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    downtime_id=1656
    
    curl -X DELETE -H "Content-type: application/json" "https://app.datadoghq.com/api/v1/downtime/${downtime_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    This end point does not return JSON on successful requests.

    Get all monitor downtimes

    Arguments
  • current_only [optional, default=false]
    Only return downtimes that are active when the request is made.
  • Signature
    GET /api/v1/downtime
    Example Request
    import time
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Get all downtimes
    api.get_all_downtimes()
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Get all downtimes
    dog.get_all_downtimes()
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -G "https://app.datadoghq.com/api/v1/downtime" \
         -d "api_key=${api_key}" \
         -d "application_key=${app_key}"
    
    Example Response
    [{'active': False,
      'disabled': True,
      'end': 1412793983,
      'id': 1625,
      'scope': ['env:staging'],
      'start': 1412792983},
     {'active': False,
      'disabled': True,
      'end': None,
      'id': 1626,
      'scope': ['*'],
      'start': 1412792985}]
    ["200",
     [{"end"=>1412793983,
       "disabled"=>true,
       "start"=>1412792983,
       "active"=>false,
       "scope"=>["env:staging"],
       "id"=>1625},
      {"end"=>nil,
       "disabled"=>true,
       "start"=>1412792985,
       "active"=>false,
       "scope"=>["*"],
       "id"=>1626}]]
    [
        {
            "active": false,
            "disabled": true,
            "end": 1412793983,
            "id": 1625,
            "scope": [
                "env:staging"
            ],
            "start": 1412792983
        },
        {
            "active": false,
            "disabled": true,
            "end": null,
            "id": 1626,
            "scope": [
                "*"
            ],
            "start": 1412792985
        }
    ]
    

    Timeboards

    This endpoint allows you to programmatically create, update delete and query timeboards.

    Create a Timeboard

    Arguments
    • title [required]
      The name of the dashboard.
    • description [required]
      A description of the dashboard's content.
    • graphs [required]
      A list of graph definitions. Graph definitions follow this form:
      • title [required]
        The name of the graph.
      • definition [required]
        The graph definition. Example:
        {"requests": [{"q": "system.cpu.idle{*} by {host}"}
    • template_variables [optional, default=None]
      A list of template variables for using Dashboard templating. Template variable definitions follow this form:
      • name [required]
        The name of the variable.
      • prefix [optional, default=None]
        The tag prefix associated with the variable. Only tags with this prefix will appear in the variable dropdown.
      • default [optional, default=None]
        The default value for the template variable on dashboard load
    Signature
    POST /api/v1/dash
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    title = "My Timeboard"
    description = "An informative timeboard."
    graphs =  [{
        "definition": {
            "events": [],
            "requests": [
                {"q": "avg:system.mem.free{*}"}
            ],
        "viz": "timeseries"
        },
        "title": "Average Memory Free"
    }]
    
    template_variables = [{
    	"name": "host1",
    	"prefix": "host",
    	"default": "host:my-host"
    }]
    
    api.create_dashboard(title, description, graphs, template_variables)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Create a timeboard.
    title = 'My First Metrics'
    description = 'And they are marvelous.'
    graphs = [{
      "definition" => {
        "events" => [],
        "requests "=> [
          {"q" => "avg:system.mem.free{*}"}
        ],
      "viz" => "timeseries"
      },
      "title" => "Average Memory Free"
    }]
    template_variables = [{
    	"name" => "host1",
    	"prefix" => "host",
    	"default" => "host:my-host"
    }]
    
    dog.create_dashboard(title, description, graphs, template_variables)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl  -X POST -H "Content-type: application/json" \
    -d '{
          "graphs" : [{
              "title": "Average Memory Free",
              "definition": {
                  "events": [],
                  "requests": [
                      {"q": "avg:system.mem.free{*}"}
                  ]
              },
              "viz": "timeseries"
          }],
          "title" : "Average Memory Free Shell",
          "description" : "A dashboard with memory info."
          "template_variables": [{
              "name": "host1",
              "prefix": "host",
              "default": "host:my-host"
          }]
        }' \
    "https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    2524
    ["200",
     {"dash"=>
       {"graphs"=>
         [{"definition"=>
            {"viz"=>"timeseries",
             "events"=>[],
             "requests "=>[{"q"=>"avg:system.mem.free{*}"}]},
           "title"=>"Average Memory Free"}],
        "description"=>"And they are marvelous.",
        "id"=>2552,
        "title"=>"My First Metrics"},
      "url"=>"/dash/dash/2552",
      "resource"=>"/api/v1/dash/2552"}]
    {
        "dash": {
            "description": "A dashboard with memory info.", 
            "graphs": [
                {
                    "definition": {
                        "events": [], 
                        "requests": [
                            {
                                "q": "avg:system.mem.free{*}"
                            }
                        ]
                    }, 
                    "title": "Average Memory Free"
                }
            ], 
            "id": 2532, 
            "title": "Average Memory Free Shell"
        }, 
        "resource": "/api/v1/dash/2532", 
        "url": "/dash/dash/2532"
    }
    

    Update a Timeboard

    Arguments
    • title [required]
      The name of the dashboard.
    • description [required]
      A description of the dashboard's contents.
    • graphs [required]
      A list of graph definitions. Graph definitions follow this form:
      • title [required]
        The name of the graph.
      • definition [required]
        The graph definition. Read the Graph Guide for more on graphs. Example:
        {"requests": [{"q": "system.cpu.idle{*} by {host}"}
    • template_variables [optional, default=None]
      A list of template variables for using Dashboard templating. Template variable definitions follow this form:
      • name [required]
        The name of the variable.
      • prefix [optional, default=None]
        The tag prefix associated with the variable. Only tags with this prefix will appear in the variable dropdown.
      • default [optional, default=None]
        The default value for the template variable on dashboard load
    Signature
    PUT /api/v1/dash/:dash_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dash_id = 2524
    title = "My Timeboard"
    description = "A new and improved timeboard!"
    graphs =  [{
        "definition": {
            "events": [],
            "requests": [
                {"q": "avg:system.mem.free{*} by {host}"}
            ],
        "viz": "timeseries"
        },
        "title": "Average Memory Free By Host"
    }]
    template_variables = [{
    	"name": "host1",
    	"prefix": "host",
    	"default": "host:my-host"
    }]
    
    api.update_dashboard(dash_id, title, description, graphs, template_variables)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dash_id = '2551'
    title = 'New and Improved Timeboard'
    description = 'This has all the new hotness.'
    graphs =  [{
      "definition" => {
        "events" => [],
        "requests "=> [
          {"q" => "avg:system.mem.free{*}"}
        ],
      "viz" => "timeseries"
      },
      "title" => "Average Memory Free"
    }]
    template_variables = [{
    	"name" => "host1",
    	"prefix" => "host",
    	"default" => "host:my-host"
    }]
    
    dog.update_dashboard(dash_id, title, description, graphs, template_variables)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    dash_id=2532
    
    curl  -X PUT -H "Content-type: application/json" \
    -d '{
          "graphs" : [{
              "title": "Sum of Memory Free",
              "definition": {
                  "events": [],
                  "requests": [
                      {"q": "sum:system.mem.free{*}"}
                  ]
              },
              "viz": "timeseries"
          }],
          "title" : "Sum Memory Free Shell",
          "description" : "A dashboard with memory info."
          "template_variables": [{
              "name": "host1",
              "prefix": "host",
              "default": "host:my-host"
          }]
        }' \
    "https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    2524
    ["200",
     {"dash"=>
       {"graphs"=>
         [{"definition"=>
            {"viz"=>"timeseries",
             "events"=>[],
             "requests "=>[{"q"=>"avg:system.mem.free{*}"}]},
           "title"=>"Average Memory Free"}],
        "description"=>"This has all the new hotness.",
        "id"=>2551,
        "title"=>"New and Improved Dashboard"},
      "url"=>"/dash/dash/2551",
      "resource"=>"/api/v1/dash/2551"}]
    {
        "dash": {
            "description": "A dashboard with memory info.", 
            "graphs": [
                {
                    "definition": {
                        "events": [], 
                        "requests": [
                            {
                                "q": "sum:system.mem.free{*}"
                            }
                        ]
                    }, 
                    "title": "Sum of Memory Free"
                }
            ], 
            "id": 2532, 
            "title": "Sum Memory Free Shell"
        }, 
        "resource": "/api/v1/dash/2532", 
        "url": "/dash/dash/2532"
    }
    

    Delete a Timeboard

    Delete an existing timeboard.

    This end point takes no JSON arguments.
    Signature
    DELETE /api/v1/dash/:dash_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dash_id = 1588
    api.delete_dashboard(dash_id)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dash_id = '2534'
    dog.delete_dashboard(dash_id)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    dash_id=2471
    
    curl -X DELETE "https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    This end point does not return JSON on successful requests.

    Get all Timeboards

    Fetch all of your timeboards' definitions.

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET /api/v1/dash
    Example Request
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl "https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}"
    
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.get_dashboards
    from dogapi import dog_http_api as api
    
    api.api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    api.dashboards()
    Example Response
    {
        "dashes": [
            {
                "description": "An informative dashboard.", 
                "id": "2473", 
                "resource": "/api/v1/dash/2473", 
                "title": "My Dashboard"
            }, 
                    {
                "description": "This has all the new hotness.", 
                "id": "2551", 
                "resource": "/api/v1/dash/2551", 
                "title": "New and Improved Dashboard"
            }
        ]
    }
    
    ["200",
     {"dashes"=>
       [{"title"=>"My Dashboard",
         "resource"=>"/api/v1/dash/2473",
         "id"=>"2473",
         "description"=>"An informative dashboard."},
         {"title"=>"My First Metrics",
         "resource"=>"/api/v1/dash/2552",
         "id"=>"2552",
         "description"=>"And they are marvelous."}
        ]}]
    [{'description': 'This has all the new hotness.',
      'id': '2551',
      'resource': '/api/v1/dash/2551',
      'title': 'New and Improved Dashboard'},
     {'description': 'And they are marvelous.',
      'id': '2552',
      'resource': '/api/v1/dash/2552',
      'title': 'My First Metrics'}
    ]

    Get a Timeboard

    Fetch an existing dashboard's definition.

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET /api/v1/dash/:dash_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dash_id = 2524
    api.dashboard(dash_id)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dash_id = '2542'
    dog.get_dashboard(dash_id)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    dash_id=2473
    
    curl "https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'description': 'A new and improved dashboard!',
     'graphs': [{
        'definition': {
           'events': [],
           'requests': [{'q': 'avg:system.mem.free{*} by {host}'}],
           'viz': 'timeseries'},
           'title': 'Average Memory Free By Host'}],
     'id': 2524,
     'title': 'My Dashboard'}
    ["200",
     {"dash"=>
       {"graphs"=>
         [{"definition"=>
            {"viz"=>"timeseries",
             "events"=>[],
             "requests "=>[{"q"=>"avg:system.mem.free{*}"}]},
           "title"=>"Average Memory Free"}],
        "description"=>"desc",
        "id"=>2542,
        "title"=>"foobar"},
      "url"=>"/dash/dash/2542",
      "resource"=>"/api/v1/dash/2542"}]
    {
        "dash": {
            "description": "An informative dashboard.", 
            "graphs": [
                {
                    "definition": {
                        "events": [], 
                        "requests": [
                            {
                                "q": "avg:system.mem.free{*}"
                            }
                        ], 
                        "viz": "timeseries"
                    }, 
                    "title": "Average Memory Free"
                }
            ], 
            "id": 2473, 
            "title": "My Dashboard"
        }, 
        "resource": "/api/v1/dash/2473", 
        "url": "/dash/dash/2473"
    }
    

    Screenboards

    You can view more detailed documentation on the Screenboard API at http://docs.datadoghq.com/api/screenboards/.

    Create a Screenboard

    Arguments
    • title [required]
      The name of the dashboard.
    • description [required]
      A description of the dashboard's content.
    • graphs [required]
      A list of graph definitions. Graph definitions follow this form:
      • title [required]
        The name of the graph.
      • widgets [required]
        The widget definition. See here for more examples.
    • template_variables [optional, default=None]
      A list of template variables for using Dashboard templating.
    • width [optional, default=None]
      Screenboard width in pixels
    • height [optional, default=None]
      Height in pixels.
    Signature
    POST /api/v1/screen
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    board = {
        "width": 1024,
        "height": 768,
        "board_title": "dogapi test",
        "widgets": [
            {
              "type": "image",
              "height": 20,
              "width": 32,
              "y": 7,
              "x": 32,
              "url": "https://path/to/image.jpg"
            }
        ]
    }
    
    api.create_screenboard(board)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    board = {
        "width" => 1024,
        "height" => 768,
        "board_title" => "dogapi test",
        "widgets" => [
            {
              "type" => "image",
              "height" => 20,
              "width" => 32,
              "y" => 7,
              "x" => 32,
              "url" => "https://path/to/image.jpg"
            }
        ]
    }
    
    result = dog.create_screenboard(board)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -X POST -H "Content-type: application/json" \
    -d '{
            "width": 1024,
            "height": 768,
            "board_title": "dogapi test",
            "widgets": [
                {
                  "type": "image",
                  "height": 20,
                  "width": 32,
                  "y": 7,
                  "x": 32,
                  "url": "https://path/to/image.jpg"
                }
            ]
        }' \
    "https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'board_title': 'dogapi test',
     'height': 768,
     'id': 7951,
     'widgets': [{'height': 20,
                  'type': 'image',
                  'url': 'https://path/to/image.jpg',
                  'width': 32,
                  'x': 32,
                  'y': 7}],
     'width': 1024}
    ["200",
     {"board_title"=>"dogapi test",
      "width"=>1024,
      "height"=>768,
      "id"=>7952,
      "widgets"=>
       [{"url"=>"https://path/to/image.jpg",
         "height"=>20,
         "width"=>32,
         "y"=>7,
         "x"=>32,
         "type"=>"image"}]}]
    {
        "board_title": "dogapi test", 
        "height": 768, 
        "id": 7953, 
        "widgets": [
            {
                "height": 20, 
                "type": "image", 
                "url": "https://path/to/image.jpg", 
                "width": 32, 
                "x": 32, 
                "y": 7
            }
        ], 
        "width": 1024
    }
    

    Delete a Screenboard

    Delete an existing screenboard.

    This end point takes no JSON arguments.
    Signature
    DELETE /api/v1/screen/:board_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    board_id = 1234
    api.delete_screenboard(board_id)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    board_id = '2534'
    result = dog.delete_screenboard(board_id)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    board_id=2471
    
    curl -X DELETE \
    "https://app.datadoghq.com/api/v1/screen/${board_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    This end point does not return JSON on successful requests.

    Get a Screenboard

    Fetch an existing screenboard's definition.

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET /api/v1/screen/:board_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    board_id = 6334
    api.get_screenboard(board_id)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    board_id = '6334'
    result = dog.get_screenboard(board_id)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    board_id=6334
    
    curl -X GET \
    "https://app.datadoghq.com/api/v1/screen/${board_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'board_title': 'dogapi test',
     'height': 768,
     'id': 6334,
     'widgets': [{'height': 20,
                  'type': 'image',
                  'url': 'http://path/to/image.jpg',
                  'width': 32,
                  'x': 32,
                  'y': 7}],
     'width': 1024}
    ["200",
     {"board_title"=>"dogapi test",
      "width"=>1024,
      "height"=>768,
      "id"=>6334,
      "widgets"=>
       [{"url"=>"http://path/to/image.jpg",
         "height"=>20,
         "width"=>32,
         "y"=>7,
         "x"=>32,
         "type"=>"image"}]}]
    {
        "board_title": "dogapi test", 
        "height": 768, 
        "id": 6334, 
        "widgets": [
            {
                "height": 20, 
                "type": "image", 
                "url": "http://path/to/image.jpg", 
                "width": 32, 
                "x": 32, 
                "y": 7
            }
        ], 
        "width": 1024
    }
    

    Share a Screenboard

    Share an existing screenboard's with a public URL.

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET /api/v1/screen/share/:board_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    board_id = 6334
    api.share_screenboard(board_id)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    board_id = '6334'
    dog.share_screenboard(board_id)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    board_id=6334
    
    curl -X GET \
    "https://app.datadoghq.com/api/v1/screen/share/${board_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {
        "board_id": 6334,
        "public_url": "https://p.datadoghq.com/sb/20756e0cd4"
    }
    ["200",
     {"board_id"=>6334, "public_url"=>"https://p.datadoghq.com/sb/20756e0cd4"}]
    {
        "board_id": 6334, 
        "public_url": "https://p.datadoghq.com/sb/20756e0cd4"
    }
    

    Tags

    The tag end point allows you to tag hosts with keywords meaningful to you - like role:database. All metrics sent from a host will have its tags applied. When fetching and applying tags to a particular host, you can refer to hosts by name (yourhost.example.com) or id (12345).

    The component of your infrastructure responsible for a tag is identified by a source. Valid sources are: nagios, hudson, jenkins, users, feed, chef, puppet, git, bitbucket, fabric, capistrano.

    Get Tags

    Return a mapping of tags to hosts for your whole infrastructure.

    Arguments
    • source [optional, default=None]
      Only show tags from a particular source. Otherwise shows all tags.
    Signature
    GET /api/v1/tags/hosts
    Example Request
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.all_tags()
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    api.all_tags()
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl "https://app.datadoghq.com/api/v1/tags/hosts?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    ["200",
     {"tags"=>
       {"role:web"=>["test.metric.host"],
        "environment:test"=>["test.metric.host"],
        "environment:production"=>["test.another.example.com"],
        "role:webserver"=>["test.another.example.com"]}}]
    {'role:database','env:test': ['test.metric.host']}
    {
        "tags": {
            "environment:production": [
                "test.another.example.com", 
                "test.host"
            ], 
            "environment:test": [
                "test.metric.host"
            ], 
            "role:database": [
                "test.metric.host"
            ], 
            "role:webserver": [
                "test.another.example.com", 
                "test.host"
            ]
        }
    }
    

    Get Host Tags

    Return the list of tags that apply to a given host.

    Arguments
    • source [optional, default=None]
      Only show tags from a particular source. Otherwise shows all tags.
    • by_source [optional, default=False]
      Return tags grouped by source.
    Signature
    GET /api/v1/tags/hosts/:host_id_or_host_name
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Get tags by host id.
    api.host_tags('108816')
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.host_tags('108816')
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    host_id=111892
    
    curl "https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    ['role:database','env:test']
    ["200", {"tags"=>["role:web", "environment:test"]}]
    {
        "tags": [
            "role:database", 
            "environment:test"
        ]
    }
    

    Add Tags to a Host

    This end point allows you to add tags to a host.

    Arguments
    • tags [required]
      A list of tags to apply to the host
    • source [optional, default=users]
      The source of the tags (e.g. chef, puppet).
    Signature
    POST /api/v1/tags/hosts/:host_id_or_host_name
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    api.add_tags('108816', ['role:webserver', 'env:production'])
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    host_id=111892
    
    curl  -X POST -H "Content-type: application/json" \
    -d '{
          "tags" : ["environment:production", "role:webserver"]
        }' \
    "https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
    
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    host_id = '108816'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.add_tags(host_id, ["role:database", "environment:production"])
    Example Response
    ['role:webserver','env:production']
    {
        "host": "test.host", 
        "tags": [
            "role:database", 
            "environment:test"
        ]
    }
    
    ["201",
     {"host"=>"test.metric.host",
      "tags"=>
       ["environment:production",
        "role:web",
        "role:database",
        "environment:test"]}]

    Update Host Tags

    This end point allows you to update all tags for a given host.

    Arguments
    • tags [required]
      A list of tags
    • source [optional, default=users]
      The source of the tags (e.g. chef, puppet).
    Signature
    PUT /api/v1/tags/hosts/:host_id_or_host_name
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    api.change_tags('108816', ['role:database', 'environment:test'])
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    host_id=111892
    
    curl -X PUT -H "Content-type: application/json" \
    -d '{
          "tags" : ["environment:production", "role:webserver"]
        }' \
    "https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
    
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    host_id = '108816'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.update_tags(host_id, ["role:web", "environment:test"])
    Example Response
    ['role:database','env:test']
    {
        "host": "test.host", 
        "tags": [
            "environment:production", 
            "role:webserver"
        ]
    }
    
    ["201", {"host"=>"test.metric.host", "tags"=>["role:web", "environment:test"]}]

    Remove Host Tags

    This end point allows you to update all tags for a given host.

    Arguments
    • source [optional, default=users]
      The source of the tags (e.g. chef, puppet).
    Signature
    DELETE /api/v1/tags/hosts/:host_id_or_host_name
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Get tags by host name.
    api.detach_tags('web.example.com')
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    host_id=111892
    
    curl -X DELETE "https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
    
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    host_id = '108816'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.detach_tags(host_id)
    Example Response
    This end point does not return JSON on successful requests.

    This end point allows you to search for entities in Datadog. The currently searchable entities are:

    • hosts
    • metrics
    Arguments
    • q [required]
      The query string
    Query Language

    Search queries allow for limited faceting. Available facets are:

    • hosts
    • metrics

    Faceting your search limits your results to only matches of the specified type. Un-faceted queries return results for all possible types.

    Un-faceted queries are of the form:

    query_string

    Faceted queries are of the form:

    facet:query_string
    Signature
    GET /api/v1/search
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Search by `host` facet.
    api.search("hosts:database")
    
    # Search by `metric` facet.
    api.search("metrics:system")
    
    # Search all facets.
    api.search("test")
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Search by `host` facet.
    dog.search("hosts:database")
    
    # Search by `metric` facet.
    dog.search("metrics:system")
    
    # Search all facets.
    dog.search("test")
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -G "https://app.datadoghq.com/api/v1/search" \
        -d "api_key=${api_key}" \
        -d "application_key=${app_key}" \
        -d "q=test"
    
    Example Response
    {'hosts': ['test.metric.host', 'test.tag.host'],
     'metrics': ['test.metric.metric', 'test.tag.metric']}
    ["200",
     {"results"=>
       {"metrics"=>["test.metric"],
        "hosts"=>
         ["test.another.example.com",
          "test.example.com",
          "test.host",
          "test.metric.host",
          "test.tag.host"]}}]
    {
        "results": {
            "hosts": [
                "test.another.example.com", 
                "test.example.com", 
                "test.host", 
                "test.metric.host", 
                "test.tag.host"
            ], 
            "metrics": [
                "test.metric"
            ]
        }
    }
    

    Comments

    Comments are how discussion happens on Datadog. You can create, edit, delete and reply to comments.

    Create a comment

    Comments are essentially special forms of events that appear in the stream. They can start a new discussion thread or optionally, reply in another thread.

    Arguments
    • message [required]
      The comment text.
    • handle [optional, default=application key owner]
      The handle of the user making the comment.
    • related_event_id [optional, default=None]
      The id of another comment or event to reply to
    Signature
    POST api/v1/comments
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Start a new discussion.
    # You can include a handle like this
    api.comment('matt@example.com', 'Should we use COBOL or Fortran?')
    
    # Or you can set it to None 
    # and the handle will default
    # to the owner of the application key
    api.comment(None, 'Should we use COBOL or Fortran?')
    
    # Reply to a discussion.
    api.comment('joe@example.com', 'Smalltalk?', related_event_id=1234)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Make a comment.
    dog.comment("I have something to say.")
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl  -X POST -H "Content-type: application/json" \
    -d '{
            "message" : "There is a problem with the database."
        }' \
    "https://app.datadoghq.com/api/v1/comments?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    123482347822
    ["200",
     {"comment"=>
       {"url"=>"/event/jump_to?event_id=1382579089039712607",
        "resource"=>"/api/v1/comments/1382579089039712607",
        "message"=>"I have something to say.",
        "handle"=>"mattp+org-carlotest141@datadoghq.com",
        "id"=>1382579089039712607}}]
    {
        "comment": {
            "handle": "mattp+org-carlotest141@datadoghq.com", 
            "id": 1382561676571697516, 
            "message": "There is a problem with the database.", 
            "resource": "/api/v1/comments/1382561676571697516", 
            "url": "/event/jump_to?event_id=1382561676571697516"
        }
    }
    

    Edit a Comment

    Arguments
    • message [optional, default=original message]
      The comment text.
    • handle [optional, default=application key owner]
      The handle of the user making the comment.
    Signature
    PUT api/v1/comments/:comment_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Edit a comment.
    comment_id = 123482347822
    api.comment('matt@example.com', 'I think differently now.', comment_id = 12345)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    comment_id="1382579089039712607"
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Update a comment.
    dog.update_comment(comment_id, :message => "I've changed my mind again")
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    comment_id=1382557387240472966
    
    curl -X PUT -H "Content-type: application/json" \
    -d '{
            "message" : "Actually, I am changing my mind."
        }' \
    "https://app.datadoghq.com/api/v1/comments/${comment_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    123482347822
    ["200",
     {"comment"=>
       {"url"=>"/event/jump_to?event_id=1382579089039712607",
        "resource"=>"/api/v1/comments/1382579089039712607",
        "message"=>"I've changed my mind again",
        "handle"=>"mattp+org-carlotest141@datadoghq.com",
        "id"=>1382579089039712607}}]
    {
        "comment": {
            "handle": "mattp+org-carlotest141@datadoghq.com", 
            "id": 1382557387240472966, 
            "message": "Actually, I am changing my mind.", 
            "resource": "/api/v1/comments/1382557387240472966", 
            "url": "/event/jump_to?event_id=1382557387240472966"
        }
    }
    

    Delete a Comment

    Arguments
    This end point takes no JSON arguments.
    Signature
    DELETE api/v1/comments/:comment_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    api.delete_comment(123412345)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.delete_comment("1378619807595725030")
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    comment_id=1382559936236196216
    
    curl -X DELETE "https://app.datadoghq.com/api/v1/comments/${comment_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    This end point does not return JSON on successful requests.

    Alerts

    The Alert API is deprecated in favor of the Monitor API. These docs will be removed in a future revision.

    Alerts allow you to watch a particular metric query and receive a notification when the value either exceeds or falls below the pre-defined threshold.

    Create an alert

    Arguments
    • query [required]
      The metric query to alert on. The syntax is:
      time_aggr(time_window):space_aggr:metric_name{tags} [by {tag_key}] operator #
      The items in square brackets are optional. All other delimiters and punctuations are required as written. The accepted arguments for each parameter are as follows:
      • time_aggr avg, sum, max, or min
      • time_window last_#m (5, 10, 15, or 30), last_#h (1, 2, or 4), or last_1d
      • space_aggr avg, sum, min, or max
      • tags one or more tags (comma-separated), or *
      • tag_key a 'key' in key:value tag syntax; defines a separate alert for each tag in the group (multi-alert)
      • operator <, <=, >, >=, ==, or !=
      • # an integer or decimal number used to set the threshold
    • name [optional, default=dynamic, based on query]
      The name of the alert.
    • message [optional, default=None]
      A message to include with notifications for this alert. Email notifications can be sent to specific users by using the same '@username' notation as events.
    • silenced [optional, default=False]
      Whether the alert should notify by email and in the event stream. An alert with 'silenced' set to 'True' is effectively muted. The alert will continue to detect state changes, but they will only be visible on the alert list page.
    • notify_no_data [optional, default=None]
      Set to 'True' to send a notification if data is missing.
    • timeout_h [optional, default=None]
      Set this value to an integer to automatically resolve the alert after the specified number of hours. For some metrics that report periodically across different tags, it may make sense to set associated alerts to auto-resolve. For instance, if a counter metric only reports when an error occurs, the triggered alert will never resolve because the metric doesn't report 0 errors.
    Signature
    POST api/v1/alert
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Create a new alert
    api.alert("avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", "Bytes received on host0", "We may need to add web hosts if this is consistently high.")
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Create a new alert
    dog.alert("avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", :name => "Bytes received on host0", :message => "We may need to add web hosts if this is consistently high.")
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    alert_id=512
    
    curl -X POST -H "Content-type: application/json" \
    -d '{
          "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
          "name": "Bytes received on host0",
          "message": "We may need to add web hosts if this is consistently high."
        }' \
        "https://app.datadoghq.com/api/v1/alert?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    525
    ["201",
     {"notify_no_data"=>false,
      "silenced"=>false,
      "creator"=>3658,
      "message"=>"We may need to add web hosts if this is consistently high.",
      "id"=>537,
      "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "name"=>"Bytes received on host0",
      "state"=>"OK",
      "event_object"=>"e7ac36c6531ccfa9e39c8988b0f28bdb"}]
    {
        "creator": 3658, 
        "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb", 
        "id": 512, 
        "message": "We may need to add web hosts if this is consistently high.", 
        "name": "Bytes received on host0", 
        "notify_no_data": false, 
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", 
        "silenced": false, 
        "state": "OK"
    }
    

    Get an alert's details

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET api/v1/alert/:alert_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Get an alert's details
    api.get_alert(525)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Get an alert's details
    dog.get_alert(537)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    alert_id=512
    
    curl -G "https://app.datadoghq.com/api/v1/alert/${alert_id}" \
         -d "api_key=${api_key}" \
         -d "application_key=${app_key}"
    
    Example Response
    {'creator': 3658,
     'event_object': 'e7ac36c6531ccfa9e39c8988b0f28bdb',
     'id': 525,
     'message': 'We may need to add web hosts if this is consistently high.',
     'name': 'Bytes received on host0',
     'notify_no_data': False,
     'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
     'silenced': False,
     'state': 'OK'}
    ["200",
     {"message"=>"We may need to add web hosts if this is consistently high.",
      "creator"=>3658,
      "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "id"=>537,
      "notify_no_data"=>false,
      "event_object"=>"e7ac36c6531ccfa9e39c8988b0f28bdb",
      "silenced"=>false,
      "name"=>"Bytes received on host0",
      "state"=>"OK"}]
    {
        "creator": 3658, 
        "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb", 
        "id": 512, 
        "message": "We may need to add web hosts if this is consistently high.", 
        "name": "Bytes received on host0", 
        "notify_no_data": false, 
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", 
        "silenced": false, 
        "state": "OK"
    }
    

    Edit an alert

    Arguments
    • query [required]
      The metric query to alert on.
    • name [optional, default=dynamic, based on query]
      The name of the alert.
    • message [optional, default=None]
      A message to include with notifications for this alert. Email notifications can be sent to specific users by using the same '@username' notation as events.
    • silenced [optional, default=False]
      Whether the alert should notify by email and in the event stream. An alert with 'silenced' set to True is effectively muted. The alert will continue to detect state changes, but they will only be visible on the alert list page.
    • silenced_timeout_ts [optional, default=None]
      An alert with 'silenced' set to True can have a silenced timeout timestamp. When the silenced timeout timestamp expires, the alert gets unmuted.
    Signature
    PUT api/v1/alert/:alert_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Edit an existing alert
    api.update_alert(525, "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", "Bytes received on host0", "We may need to add web hosts if this is consistently high.", silenced=True, silenced_timeout_ts=1401833000)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Edit an existing alert
    dog.update_alert(537, "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", :message => "Bytes received on host0", :name => "We may need to add web hosts if this is consistently high.", :silenced => true, :silenced_timeout_ts => 1401833000)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    alert_id=512
    
    curl -X PUT -H "Content-type: application/json" \
    -d '{
          "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
          "name": "Bytes received on host0",
          "message": "We may need to add web hosts if this is consistently high.",
          "silenced": true,
          "silenced_timeout_ts": 1401833000
        }' \
        "https://app.datadoghq.com/api/v1/alert/${alert_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    525
    ["200",
     {"query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "silenced"=>true,
      "silenced_timeout_ts"=>1401833000,
      "message"=>"Bytes received on host0",
      "name"=>"We may need to add web hosts if this is consistently high.",
      "notify_no_data"=>false,
      "state"=>"OK",
      "event_object"=>"0af4b37f8edaf5c810547a35e2e23ea1",
      "id"=>537,
      "creator"=>3658}]
    {
        "creator": 3658,
        "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb",
        "id": 512,
        "message": "We may need to add web hosts if this is consistently high.",
        "name": "Bytes received on host0",
        "notify_no_data": false,
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
        "silenced": true,
        "silenced_timeout_ts": 1401833000,
        "state": "OK"
    }
    

    Delete an alert

    Arguments
    This end point takes no JSON arguments.
    Signature
    DELETE api/v1/alert/:alert_id
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Delete an alert
    api.delete_alert(525)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Delete an alert
    dog.delete_alert(537)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    alert_id=512
    
    curl -X DELETE "https://app.datadoghq.com/api/v1/alert/${alert_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'creator': 3658,
     'event_object': 'e7ac36c6531ccfa9e39c8988b0f28bdb',
     'message': 'We may need to add web hosts if this is consistently high.',
     'name': 'Bytes received on host0',
     'notify_no_data': False,
     'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
     'silenced': True,
     'state': 'OK'}
    ["200",
     {"creator"=>3658,
      "name"=>"We may need to add web hosts if this is consistently high.",
      "event_object"=>"0af4b37f8edaf5c810547a35e2e23ea1",
      "notify_no_data"=>false,
      "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "silenced"=>true,
      "message"=>"Bytes received on host0",
      "state"=>"OK"}]
    {
        "creator": 3658, 
        "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb", 
        "message": "We may need to add web hosts if this is consistently high.", 
        "name": "Bytes received on host0", 
        "notify_no_data": false, 
        "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", 
        "silenced": true, 
        "state": "OK"
    }
    

    Get all alert details

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET api/v1/alert
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Get all alert details
    api.get_all_alerts()
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Get all alert details
    dog.get_all_alerts()
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -G "https://app.datadoghq.com/api/v1/alert" \
         -d "api_key=${api_key}" \
         -d "application_key=${app_key}"
    
    Example Response
    [{'creator': 3658,
      'event_object': 'e7ac36c6531ccfa9e39c8988b0f28bdb',
      'id': 522,
      'message': 'We may need to add web hosts if this is consistently high.',
      'name': 'Bytes received on host0',
      'notify_no_data': False,
      'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
      'silenced': False,
      'state': 'Alert'}]
    ["200",
     {"alerts"=>
       [{"id"=>273,
         "state"=>"No Data",
         "silenced"=>false,
         "message"=>" @pagerduty",
         "query"=>"avg(last_10m):max:system.load.5{host:alexsolo} > 6",
         "name"=>"Load AVG on host:alexsolo",
         "event_object"=>"f64854a9d66cd1eea9d77ec82588ff91",
         "notify_no_data"=>false,
         "creator"=>3658}]}]
    {
        "alerts": [
            {
                "creator": 3658, 
                "event_object": "f64854a9d66cd1eea9d77ec82588ff91", 
                "id": 273, 
                "message": " @pagerduty", 
                "name": "Load AVG on host:alexsolo", 
                "notify_no_data": false, 
                "query": "avg(last_10m):max:system.load.5{host:alexsolo} > 6", 
                "silenced": false, 
                "state": "OK"
            }, 
            {
                "creator": 3658, 
                "event_object": "f64854a9d66cd1eea9d77ec82588ff91", 
                "id": 274, 
                "message": " @pagerduty", 
                "name": "Load AVG on host:alexsolo", 
                "notify_no_data": false, 
                "query": "avg(last_1m):max:system.load.5{host:alexsolo} > 6", 
                "silenced": false, 
                "state": "OK"
            }
        ]
    }
    

    Mute all alerting

    Muting will prevent all alerts from notifying through email and posts to the event stream. State changes will only be visible by checking the alert page.

    Arguments
    This end point takes no JSON arguments.
    Signature
    POST api/v1/mute_alerts
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Mute all alerts
    api.mute_alerts()
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Mute all alerts
    dog.mute_alerts()
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -X POST "https://app.datadoghq.com/api/v1/mute_alerts?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    This end point does not return JSON on successful requests.

    Unmute all alerting

    Arguments
    This end point takes no JSON arguments.
    Signature
    POST api/v1/unmute_alerts
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Unmute all alerts
    api.unmute_alerts()
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    # Unmute all alerts
    dog.unmute_alerts()
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -X POST "https://app.datadoghq.com/api/v1/unmute_alerts?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    This end point does not return JSON on successful requests.

    Users

    You can invite users to join DataDog using the API.

    Invite Users

    Arguments
    • emails [required]
      A list of email addresses to send an invite to.
    Signature
    POST api/v1/invite_users
    Example Request
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Send invites
    api.invite(["jack@example.com", "jill@example.com"])
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    dog.invite(["jack@example.com", "jill@example.com"])
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    alert_id=512
    
    curl -X POST -H "Content-type: application/json" \
    -d '{
          "emails": ["jack@example.com", "jill@example.com"]
        }' \
        "https://app.datadoghq.com/api/v1/invite_users?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    ["jack@example.com", "jill@example.com"]
    ["200", 
        {"emails"=>["jack@example.com", "jill@example.com"]}
    ]
    {"emails": ["jack@example.com", "jill@example.com"]}

    Graphs

    You can take graph snapshots using the API.

    Graph Snapshot

    Arguments
    • metric_query [required]
      The metric query.
    • start [required]
      The POSIX timestamp of the start of the query.
    • end [required]
      The POSIX timestamp of the end of the query.
    • event_query [optional, default=None]
      A query that will add event bands to the graph.
    Signature
    GET api/v1/graph/snapshot
    Example Request
    import time
    from dogapi import dog_http_api as api
    
    api.api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
    api.application_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    # Take a graph snapshot
    end = int(time.time())
    start = end - (60 * 60)
    api.graph_snapshot("system.load.1{*}", start, end)
    require 'rubygems'
    require 'dogapi'
    
    api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
    app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
    
    dog = Dogapi::Client.new(api_key, app_key)
    
    end_ts = Time.now().to_i
    start_ts = end_ts - (60 * 60)
    dog.graph_snapshot("system.load.1{*}", start_ts, end_ts)
    curl -G -H "Content-type: application/json" \
        -d "metric_query=system.load.1{*}" \
        -d "start=1346272158" \
        -d "end=1346274158" \
        -d "api_key=9775a026f1ca7d1c6c5af9d94d9595a4" \
        -d "application_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" \
        'https://app.datadoghq.com/api/v1/graph/snapshot'
    Example Response
    {'event_query': 'None',
     'metric_query': 'system.load.1{*}',
     'snapshot_url': 'https://s3.amazonaws.com/dd-snapshots-prod/org_1499/2013-07-19/2459d291fc021c84f66aac3a87251b6c92b589da.png'}
    ["200",
     {"metric_query"=>"system.load.1{*}",
      "snapshot_url"=>
       "https://s3.amazonaws.com/dd-snapshots-prod/org_1499/2013-07-19/7f6dd29198ce0872a6fdfab33f534ef8d64a23ea.png"}]
    {
        "metric_query": "system.load.1{*}", 
        "snapshot_url": "https://s3.amazonaws.com/dd-snapshots-prod/org_1499/2013-07-19/53fd79f024e7796f4ca399f1d90adf3cf95a9bb8.png"
    }
    

    Troubleshooting

    We do very minimal error checking on the API front-end, as we queue all data for asynchronous processing (the goal being to always, always accept your data in production situations and decouple our systems from yours).

    Thus it is possible you could receive a 202 'success' response but not see your data in Datadog. The cause of this is most likely:

    • Problems with the timestamp (either not in seconds or in the past, etc.)
    • Using the application key instead of API key
    • Events are succeeding, but because success events are low priority, they don't show up in the event stream until it is switched to priority 'all'

    To check your timestamp is correct run:
    date -u && curl -s -v https://app.datadoghq.com/intake 2>&1 | grep Date
    This will output the current system’s date, and then make a request to our endpoint and grab the date on our end. If these are more than a few minutes apart, you may want to look at the time settings on your server.


    There are also certain fields which are not mandatory for submission, but do require a valid input. For example, in submitting an event the priority field must be one of the four given options. Any other text will result in a 202 'success' but no event showing up. Having an invalid source_type_name will not prevent the event from showing up, but that field will be dropped upon submission.