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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)
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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

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

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

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

# Submit a point with a host and tags.
api.Metric.send(metric='my.series', points=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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

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

api.Event.create(title=title, text=text, tags=tags)
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
{'event': {'date_happened': 1419436860,
  'handle': None,
  'id': 2603387619536318140,
  'priority': None,
  'related_event_id': None,
  'tags': ['version:1', 'application:web'],
  'text': 'And let me tell you all about it here!',
  'title': 'Something big happened!',
  'url': 'https://app.datadoghq.com/event/jump_to?event_id=2603387619536318140'},
 'status': 'ok'}
{
    "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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

api.Event.get(2603387619536318140)
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
{'event': {'alert_type': 'info',
  'date_happened': 1419436860,
  'device_name': None,
  'host': None,
  'id': 2603387619536318140,
  'payload': '{}',
  'priority': 'normal',
  'resource': '/api/v1/events/2603387619536318140',
  '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=2603387619536318140'}}
{
    "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 string of sources
  • tags [optional, default=None]
    A comma separated string of tags
Signature
GET /api/v1/events
Example Request
from datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)


start_time = 1419436850
end_time = 1419436870

api.Event.query(start=start_time, end=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': 1419436860,
  'device_name': None,
  'host': None,
  'id': 2603387619536318140,
  'is_aggregate': False,
  'priority': 'normal',
  'resource': '/api/v1/events/2603387619536318140',
  '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=2603387619536318140'},
  {'alert_type': 'info',
  'comments': [],
  'date_happened': 1419436865,
  'device_name': None,
  'host': None,
  'id': 2603387619536318141,
  'is_aggregate': False,
  'priority': 'normal',
  'resource': '/api/v1/events/2603387619536318141',
  '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=2603387619536318141'}]
["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 occurred
  • tags [optional, default=None]
    A list of key:val tags for this check
Signature
POST /api/v1/check_run
Example Request
from datadog import initialize, api
from datadog.api.constants import CheckStatus

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

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

api.ServiceCheck.check(check=check, host_name=host, status=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, min, change, or pct_change
    • 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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

# Create a new monitor
options = {
    "notify_no_data": True,
    "no_data_timeframe": 20
}
api.Monitor.create(type="metric alert", 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.", 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
{'creator': {'email': 'matt@example.com',
  'handle': 'matt@example.com',
  'id': 1896,
  'name': u'Matt'},
 'id': 2081,
 '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': 2,
 'overall_state': 'No Data',
 '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"=>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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

# Get a monitor's details
api.Monitor.get(2081)
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': 2081,
 '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': 2,
 'overall_state': 'No Data',
 '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.Monitor.update(2081, 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.")
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
{'id': 2081,
 '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': 2,
 'overall_state': 'No Data',
 'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
 'type': 'metric alert'}
["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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

# Delete a monitor
api.Monitor.delete(2081)
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': 2081}
["200", {"deleted_monitor_id"=>62625}]
{
    "deleted_monitor_id": 59409
}

Get all monitor details

Arguments
  • group_states [optional, default=None]
    A string list 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 list indicating what tags, if any, should be used to filter the list of monitors by scope
Signature
GET /api/v1/monitor
Example Request
from datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

# Get all monitor details
api.Monitor.get_all()
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
[ {'creator': {'email': 'matt@example.com',
   'handle': 'matt@example.com',
   'id': 1896,
   'name': u'Matt'},
  'id': 2085,
  'message': u'',
  'name': '**system.net.bytes_rcvd** over **host:host0** was **> 100** on average during the **last 1h**.',
  'options': {'notify_audit': False, 'notify_no_data': False, 'silenced': {}},
  'org_id': 2,
  'overall_state': 'No Data',
  'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
  'type': 'metric alert'},
 {'creator': {'email': 'matt@example.com',
   'handle': 'matt@example.com',
   'id': 1896,
   'name': u'Matt'},
  'id': 2083,
  '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': 2,
  'overall_state': 'No Data',
  '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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

# Mute all monitors
api.Monitor.mute_all()
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': 2728,
 'message': None,
 'scope': ['*'],
 'start': 1419440110}
["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 datadog import initialize, api

options = {
    'api_key': 'api_key',
    'app_key': 'app_key'
}

initialize(**options)

# Unmute all alerts
api.Monitor.unmute_all()
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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Mute a monitor
    api.Monitor.mute(2088)
    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': 2088,
     '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': {'*': None}},
     'org_id': 2,
     'overall_state': 'No Data',
     'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
     '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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Unmute all alerts
    api.Monitor.unmute(2088)
    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': 2088,
     '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': 2,
     'overall_state': 'No Data',
     'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
     '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"
    }
    

    Downtimes

    Downtiming gives you greater control over monitor notifications by allowing you to globally exclude scopes from alerting. Downtime settings, which can be scheduled with start and end times, prevent all alerting related to specified Datadog tags.

    Schedule monitor downtime

    Arguments
  • scope [required]
    The scope to apply the downtime to, e.g. 'host:app2'
  • start [optional, default=None]
    POSIX timestamp to start the downtime. In the default case, the downtime will start immediately.
  • 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
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Schedule downtime
    api.Downtime.create(scope='env:staging', start=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', :start => 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
    {'active': False,
     'disabled': False,
     'end': None,
     'id': 2910,
     'message': None,
     'scope': ['env:staging'],
     'start': 1420387032}
    ["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
  • id [required]
    The integer id of the downtime to be updated
  • 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
    PUT /api/v1/downtime/:downtime_id
    Example Request
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Update downtime
    api.Downtime.update(4336, scope='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
    {'active': True,
     'disabled': False,
     'end': 1420447087,
     'id': 2910,
     'message': 'Doing some testing on staging.',
     'scope': ['env:staging'],
     'start': 1420387032}
    ["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
  • id [required]
    The integer id of the downtime to be canceled
  • Signature
    DELETE /api/v1/downtime/:downtime_id
    Example Request
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Cancel downtime
    api.Downtime.delete(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 a monitor downtime

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET /api/v1/downtime/:downtime_id
    Example Request
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Get a downtime
    api.Downtime.get(2910)
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    downtime_id=2473
    
    curl "https://app.datadoghq.com/api/v1/downtime/${downtime_id}?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    {'active': True,
     'disabled': False,
     'end': 1420447087,
     'id': 2910,
     'message': 'Doing some testing on staging.',
     'scope': ['env:staging'],
     'start': 1420387032}
    {'active': True,
     'disabled': False,
     'end': 1420447087,
     'id': 2910,
     'message': 'Doing some testing on staging.',
     'scope': ['env:staging'],
     'start': 1420387032}
    

    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
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Get all downtimes
    api.Downtime.get_all()
    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    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.Timeboard.create(title=title, description=description, graphs=graphs, template_variables=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
    {'dash': {'description': 'An informative timeboard.',
      'graphs': [{'definition': {'events': [],
         'requests': [{'q': 'avg:system.mem.free{*}'}],
         'viz': 'timeseries'},
        'title': 'Average Memory Free'}],
      'id': 4952,
      'template_variables': [{'default': 'host:my-host',
        'name': 'host1',
        'prefix': 'host'}],
      'title': 'My Timeboard'},
     'resource': '/api/v1/dash/4952',
     'url': '/dash/dash/4952'}
    ["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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    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.Timeboard.update(4952, title=title, description=description, graphs=graphs, template_variables=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
    {'dash': {'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'}],
      'id': 4952,
      'template_variables': [{'default': 'host:my-host',
        'name': 'host1',
        'prefix': 'host'}],
      'title': 'My Timeboard'},
     'resource': '/api/v1/dash/4952',
     'url': '/dash/dash/4952'}
    ["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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Timeboard.delete(4952)
    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Timeboard.get_all()
    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Timeboard.get(4953)
    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
    {'dash': {'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'}],
      'id': 4953,
      'template_variables': [{'default': 'host:my-host',
        'name': 'host1',
        'prefix': 'host'}],
      'title': 'My Timeboard'},
     'resource': '/api/v1/dash/4953',
     'url': '/dash/dash/4953'}
    ["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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    title = "My Screenboard"
    description = "An informative screenboard."
    width = 1024
    board = [{
      "type": "image",
      "height": 20,
      "width": 32,
      "y": 7,
      "x": 32,
      "url": "https://path/to/image.jpg"
      }
      ]
    template_variables = [{
      "name": "host1",
      "prefix": "host",
      "default": "host:my-host"
    }]
    
    api.Screenboard.create(title=title, description=description, graphs=board,
      template_variables=template_variables, width=width)
    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
    {'description': 'An informative screenboard.',
     'graphs': [{'height': 20,
       'type': 'image',
       'url': 'https://path/to/image.jpg',
       'width': 32,
       'x': 32,
       'y': 7}],
     'id': 811,
     'template_variables': [{'default': 'host:my-host',
       'name': 'host1',
       'prefix': 'host'}],
     'title': 'My Screenboard',
     '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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Screenboard.delete(811)
    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Screenboard.get(811)
    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
    {'description': 'An informative screenboard.',
     'graphs': [{'height': 20,
       'type': 'image',
       'url': 'https://path/to/image.jpg',
       'width': 32,
       'x': 32,
       'y': 7}],
     'id': 811,
     'template_variables': [{'default': 'host:my-host',
       'name': 'host1',
       'prefix': 'host'}],
     'title': 'My Screenboard',
     '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
    }
    

    Get all Screenboards

    Fetch all of your screenboards' definitions.

    Arguments
    This end point takes no JSON arguments.
    Signature
    GET /api/v1/screen
    Example Request
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Screenboard.get_all()
    api_key=9775a026f1ca7d1c6c5af9d94d9595a4
    app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
    
    curl -X GET "https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}"
    
    Example Response
    [{'description': 'This has all the new hotness.',
      'id': '2551',
      'resource': '/api/v1/screen/2551',
      'title': 'New and Improved Screenboard'},
     {'description': 'And they are marvelous.',
      'id': '2552',
      'resource': '/api/v1/screen/2552',
      'title': 'My First Metrics'}
    ]
    [{'description': 'This has all the new hotness.',
      'id': '2551',
      'resource': '/api/v1/screen/2551',
      'title': 'New and Improved Screenboard'},
     {'description': 'And they are marvelous.',
      'id': '2552',
      'resource': '/api/v1/screen/2552',
      'title': 'My First Metrics'}
    ]
    

    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Screenboard.share(812)
    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': 812,
     '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"
    }
    

    Hosts

    Mute a Host

    Arguments
    • hostname [required]
      The host's name to mute.
    • end [optional, default=None]
      POSIX timestamp when to unmute host. If omitted, host will be muted until explicitly unmuted).
    • override [optional, default=False]
      If true and the host is already muted, will overwrite existing end on the host.
    Signature
    POST /api/v1/host
    Example Request
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Mute a host
    api.Monitor.mute('test.host')
    Example Response
    {'action': 'Muted', 'hostname': 'test.host'}

    Unmute a Host

    Arguments
    • hostname [required]
      The host's name to unmute.
    Signature
    POST /api/v1/host
    Example Request
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Unmute host
    api.Host.unmute('test.host')
    Example Response
    {'action': 'Unmuted', 'hostname': 'test.host'}

    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Tag.get_all()
    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"]}}]
    {
        "tags": {
            "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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Get tags by host id.
    api.Tag.get('hostname')
    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
    {'tags': ['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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Tag.create('hostname', ['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
    {'host': 'hostname', 'tags': ['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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Tag.update('hostname', tags=['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
    {'host': 'hostname', 'tags': ['role:database','environment: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 remove 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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Tag.delete('hostname')
    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 from the last 24 hours 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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Search by `host` facet.
    api.Infrastructure.search(q="hosts:database")
    
    # Search by `metric` facet.
    api.Infrastructure.search(q="metrics:system")
    
    # Search all facets.
    api.Infrastructure.search(q="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
    {'results': {'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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options))
    
    # Start a new discussion.
    # You can include a handle like this
    api.Comment.create(handle='matt@example.com', message='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.create(message='Should we use COBOL or Fortran?')
    
    # Reply to a discussion.
    api.Comment.create(handle='joe@example.com', message='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
    {'comment': {'handle': 'matt@example.com',
      'id': 2603645287324504065,
      'message': 'Should we use COBOL or Fortran?',
      'resource': '/api/v1/comments/2603645287324504065',
      'url': '/event/jump_to?event_id=2603645287324504065'}}
    ["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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Edit a comment.
    api.Comment.update(2603645287324504065, message='I think differently now.')
    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
    {'comment': {'handle': 'matt@example.com',
      'id': 2603645287324504065,
      'message': 'I think differently now.',
      'resource': '/api/v1/comments/2603645287324504065',
      'url': '/event/jump_to?event_id=2603645287324504065'}}
    ["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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    api.Comment.delete(2603645287324504065)
    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.

    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 datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Send invites
    api.User.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
    {'emails': ['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
    from datadog import initialize, api
    
    options = {
        'api_key': 'api_key',
        'app_key': 'app_key'
    }
    
    initialize(**options)
    
    # Take a graph snapshot
    end = int(time.time())
    start = end - (60 * 60)
    api.Graph.create(metric_query="system.load.1", start=start, end=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
    {'graph_def': '{"requests": [{"q": "system.load.1"}]}',
     '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.