API Reference

Overview

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

Authentication

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

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

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

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

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

Success and Errors

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

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

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

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

Metrics

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

Post time series points

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

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

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

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

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

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

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

api_key = "abcdef123456"

dog = Dogapi::Client.new(api_key)

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

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

Events

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

Post an Event

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

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

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

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

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

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

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

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

dog.emit_event(Dogapi::Event.new('msg_text', :msg_title => 'Title'))
Example Response
1378859520391900319
{
    "event": {
        "date_happened": 1346449298, 
        "handle": null, 
        "id": 1378859526682864843, 
        "priority": "normal", 
        "related_event_id": null, 
        "tags": [
            "environment:test"
        ], 
        "text": null, 
        "title": "Did you hear the news today?", 
        "url": "https://app.datadoghq.com/event/jump_to?event_id=1378859526682864843"
    }, 
    "status": "ok"
}
["202",
 {"status"=>"ok",
  "event"=>
   {"priority"=>"normal",
    "date_happened"=>1346452418,
    "title"=>"Title",
    "url"=>
     "https://app.datadoghq.com/event/jump_to?event_id=1378911893708573827",
    "text"=>"msg_text",
    "tags"=>[],
    "related_event_id"=>nil,
    "id"=>1378911893708573827}}]

Get an Event

This end point allows you to query for event details.

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

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

event_id = '1375909614428331251'

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

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

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

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

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

Query the Event Stream

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

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

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


start_time = 1346272158
end_time = 1346274158

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

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

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

start_time = 1346272158
end_time = 1346274158

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

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

Timeboards

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

Create a Timeboard

Arguments
  • title [required]
    The name of the dashboard.
  • description [required]
    A description of the dashboard's content.
  • graphs [required]
    A list of graph definitions. Graph definitions follow this form:
    • title [required]
      The name of the graph.
    • definition [required]
      The graph definition. Example:
      {"requests": [{"q": "system.cpu.idle{*} by {host}"}
  • template_variables [optional, default=None]
    A list of template variables for using Dashboard templating. Template variable definitions follow this form:
    • name [required]
      The name of the variable.
    • prefix [optional, default=None]
      The tag prefix associated with the variable. Only tags with this prefix will appear in the variable dropdown.
    • default [optional, default=None]
      The default value for the template variable on dashboard load
Signature
POST /api/v1/dash
Example Request
from dogapi import dog_http_api as api

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

title = "My Timeboard"
description = "An informative timeboard."
graphs =  [{
    "definition": {
        "events": [],
        "requests": [
            {"q": "avg:system.mem.free{*}"}
        ],
    "viz": "timeseries"
    },
    "title": "Average Memory Free"
}]

template_variables = [{
	"name": "host1",
	"prefix": "host",
	"default": "host:my-host"
}]

api.create_dashboard(title, description, graphs, template_variables)
require 'rubygems'
require 'dogapi'

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

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

# Create a timeboard.
title = 'My First Metrics'
description = 'And they are marvelous.'
graphs = [{
  "definition" => {
    "events" => [],
    "requests "=> [
      {"q" => "avg:system.mem.free{*}"}
    ],
  "viz" => "timeseries"
  },
  "title" => "Average Memory Free"
}]
template_variables = [{
	"name" => "host1",
	"prefix" => "host",
	"default" => "host:my-host"
}]

dog.create_dashboard(title, description, graphs, template_variables)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info."
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
    }' \
"https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}"
Example Response
2524
["200",
 {"dash"=>
   {"graphs"=>
     [{"definition"=>
        {"viz"=>"timeseries",
         "events"=>[],
         "requests "=>[{"q"=>"avg:system.mem.free{*}"}]},
       "title"=>"Average Memory Free"}],
    "description"=>"And they are marvelous.",
    "id"=>2552,
    "title"=>"My First Metrics"},
  "url"=>"/dash/dash/2552",
  "resource"=>"/api/v1/dash/2552"}]
{
    "dash": {
        "description": "A dashboard with memory info.", 
        "graphs": [
            {
                "definition": {
                    "events": [], 
                    "requests": [
                        {
                            "q": "avg:system.mem.free{*}"
                        }
                    ]
                }, 
                "title": "Average Memory Free"
            }
        ], 
        "id": 2532, 
        "title": "Average Memory Free Shell"
    }, 
    "resource": "/api/v1/dash/2532", 
    "url": "/dash/dash/2532"
}

Update a Timeboard

Arguments
  • title [required]
    The name of the dashboard.
  • description [required]
    A description of the dashboard's contents.
  • graphs [required]
    A list of graph definitions. Graph definitions follow this form:
    • title [required]
      The name of the graph.
    • definition [required]
      The graph definition. Read the Graph Guide for more on graphs. Example:
      {"requests": [{"q": "system.cpu.idle{*} by {host}"}
  • template_variables [optional, default=None]
    A list of template variables for using Dashboard templating. Template variable definitions follow this form:
    • name [required]
      The name of the variable.
    • prefix [optional, default=None]
      The tag prefix associated with the variable. Only tags with this prefix will appear in the variable dropdown.
    • default [optional, default=None]
      The default value for the template variable on dashboard load
Signature
PUT /api/v1/dash/:dash_id
Example Request
from dogapi import dog_http_api as api

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

dash_id = 2524
title = "My Timeboard"
description = "A new and improved timeboard!"
graphs =  [{
    "definition": {
        "events": [],
        "requests": [
            {"q": "avg:system.mem.free{*} by {host}"}
        ],
    "viz": "timeseries"
    },
    "title": "Average Memory Free By Host"
}]
template_variables = [{
	"name": "host1",
	"prefix": "host",
	"default": "host:my-host"
}]

api.update_dashboard(dash_id, title, description, graphs, template_variables)
require 'rubygems'
require 'dogapi'

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

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

dash_id = '2551'
title = 'New and Improved Timeboard'
description = 'This has all the new hotness.'
graphs =  [{
  "definition" => {
    "events" => [],
    "requests "=> [
      {"q" => "avg:system.mem.free{*}"}
    ],
  "viz" => "timeseries"
  },
  "title" => "Average Memory Free"
}]
template_variables = [{
	"name" => "host1",
	"prefix" => "host",
	"default" => "host:my-host"
}]

dog.update_dashboard(dash_id, title, description, graphs, template_variables)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
dash_id=2532

curl  -X PUT -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Sum of Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "sum:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Sum Memory Free Shell",
      "description" : "A dashboard with memory info."
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
    }' \
"https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
2524
["200",
 {"dash"=>
   {"graphs"=>
     [{"definition"=>
        {"viz"=>"timeseries",
         "events"=>[],
         "requests "=>[{"q"=>"avg:system.mem.free{*}"}]},
       "title"=>"Average Memory Free"}],
    "description"=>"This has all the new hotness.",
    "id"=>2551,
    "title"=>"New and Improved Dashboard"},
  "url"=>"/dash/dash/2551",
  "resource"=>"/api/v1/dash/2551"}]
{
    "dash": {
        "description": "A dashboard with memory info.", 
        "graphs": [
            {
                "definition": {
                    "events": [], 
                    "requests": [
                        {
                            "q": "sum:system.mem.free{*}"
                        }
                    ]
                }, 
                "title": "Sum of Memory Free"
            }
        ], 
        "id": 2532, 
        "title": "Sum Memory Free Shell"
    }, 
    "resource": "/api/v1/dash/2532", 
    "url": "/dash/dash/2532"
}

Delete a Timeboard

Delete an existing timeboard.

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

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

dash_id = 1588
api.delete_dashboard(dash_id)
require 'rubygems'
require 'dogapi'

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

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

dash_id = '2534'
dog.delete_dashboard(dash_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
dash_id=2471

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

Get all Timeboards

Fetch all of your timeboards' definitions.

Arguments
This end point takes no JSON arguments.
Signature
GET /api/v1/dash
Example Request
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

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

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

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

dog.get_dashboards
from dogapi import dog_http_api as api

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

api.dashboards()
Example Response
{
    "dashes": [
        {
            "description": "An informative dashboard.", 
            "id": "2473", 
            "resource": "/api/v1/dash/2473", 
            "title": "My Dashboard"
        }, 
                {
            "description": "This has all the new hotness.", 
            "id": "2551", 
            "resource": "/api/v1/dash/2551", 
            "title": "New and Improved Dashboard"
        }
    ]
}
["200",
 {"dashes"=>
   [{"title"=>"My Dashboard",
     "resource"=>"/api/v1/dash/2473",
     "id"=>"2473",
     "description"=>"An informative dashboard."},
     {"title"=>"My First Metrics",
     "resource"=>"/api/v1/dash/2552",
     "id"=>"2552",
     "description"=>"And they are marvelous."}
    ]}]
[{'description': 'This has all the new hotness.',
  'id': '2551',
  'resource': '/api/v1/dash/2551',
  'title': 'New and Improved Dashboard'},
 {'description': 'And they are marvelous.',
  'id': '2552',
  'resource': '/api/v1/dash/2552',
  'title': 'My First Metrics'}
]

Get a Timeboard

Fetch an existing dashboard's definition.

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

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

dash_id = 2524
api.dashboard(dash_id)
require 'rubygems'
require 'dogapi'

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

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

dash_id = '2542'
dog.get_dashboard(dash_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
dash_id=2473

curl "https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{'description': 'A new and improved dashboard!',
 'graphs': [{
    'definition': {
       'events': [],
       'requests': [{'q': 'avg:system.mem.free{*} by {host}'}],
       'viz': 'timeseries'},
       'title': 'Average Memory Free By Host'}],
 'id': 2524,
 'title': 'My Dashboard'}
["200",
 {"dash"=>
   {"graphs"=>
     [{"definition"=>
        {"viz"=>"timeseries",
         "events"=>[],
         "requests "=>[{"q"=>"avg:system.mem.free{*}"}]},
       "title"=>"Average Memory Free"}],
    "description"=>"desc",
    "id"=>2542,
    "title"=>"foobar"},
  "url"=>"/dash/dash/2542",
  "resource"=>"/api/v1/dash/2542"}]
{
    "dash": {
        "description": "An informative dashboard.", 
        "graphs": [
            {
                "definition": {
                    "events": [], 
                    "requests": [
                        {
                            "q": "avg:system.mem.free{*}"
                        }
                    ], 
                    "viz": "timeseries"
                }, 
                "title": "Average Memory Free"
            }
        ], 
        "id": 2473, 
        "title": "My Dashboard"
    }, 
    "resource": "/api/v1/dash/2473", 
    "url": "/dash/dash/2473"
}

Screenboards

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

Create a Screenboard

Arguments
  • title [required]
    The name of the dashboard.
  • description [required]
    A description of the dashboard's content.
  • graphs [required]
    A list of graph definitions. Graph definitions follow this form:
    • title [required]
      The name of the graph.
    • widgets [required]
      The widget definition. See here for more examples.
  • template_variables [optional, default=None]
    A list of template variables for using Dashboard templating.
  • width [optional, default=None]
    Screenboard width in pixels
  • height [optional, default=None]
    Height in pixels.
Signature
POST /api/v1/screen
Example Request
from dogapi import dog_http_api as api

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

board = {
    "width": 1024,
    "height": 768,
    "board_title": "dogapi test",
    "widgets": [
        {
          "type": "image",
          "height": 20,
          "width": 32,
          "y": 7,
          "x": 32,
          "url": "https://path/to/image.jpg"
        }
    ]
}

api.create_screenboard(board)
require 'rubygems'
require 'dogapi'

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

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

board = {
    "width" => 1024,
    "height" => 768,
    "board_title" => "dogapi test",
    "widgets" => [
        {
          "type" => "image",
          "height" => 20,
          "width" => 32,
          "y" => 7,
          "x" => 32,
          "url" => "https://path/to/image.jpg"
        }
    ]
}

result = dog.create_screenboard(board)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -X POST -H "Content-type: application/json" \
-d '{
        "width": 1024,
        "height": 768,
        "board_title": "dogapi test",
        "widgets": [
            {
              "type": "image",
              "height": 20,
              "width": 32,
              "y": 7,
              "x": 32,
              "url": "https://path/to/image.jpg"
            }
        ]
    }' \
"https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}"
Example Response
{'board_title': 'dogapi test',
 'height': 768,
 'id': 7951,
 'widgets': [{'height': 20,
              'type': 'image',
              'url': 'https://path/to/image.jpg',
              'width': 32,
              'x': 32,
              'y': 7}],
 'width': 1024}
["200",
 {"board_title"=>"dogapi test",
  "width"=>1024,
  "height"=>768,
  "id"=>7952,
  "widgets"=>
   [{"url"=>"https://path/to/image.jpg",
     "height"=>20,
     "width"=>32,
     "y"=>7,
     "x"=>32,
     "type"=>"image"}]}]
{
    "board_title": "dogapi test", 
    "height": 768, 
    "id": 7953, 
    "widgets": [
        {
            "height": 20, 
            "type": "image", 
            "url": "https://path/to/image.jpg", 
            "width": 32, 
            "x": 32, 
            "y": 7
        }
    ], 
    "width": 1024
}

Delete a Screenboard

Delete an existing screenboard.

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

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

board_id = 1234
api.delete_screenboard(board_id)
require 'rubygems'
require 'dogapi'

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

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

board_id = '2534'
result = dog.delete_screenboard(board_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
board_id=2471

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

Get a Screenboard

Fetch an existing screenboard's definition.

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

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

board_id = 6334
api.get_screenboard(board_id)
require 'rubygems'
require 'dogapi'

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

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

board_id = '6334'
result = dog.get_screenboard(board_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
board_id=6334

curl -X GET \
"https://app.datadoghq.com/api/v1/screen/${board_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{'board_title': 'dogapi test',
 'height': 768,
 'id': 6334,
 'widgets': [{'height': 20,
              'type': 'image',
              'url': 'http://path/to/image.jpg',
              'width': 32,
              'x': 32,
              'y': 7}],
 'width': 1024}
["200",
 {"board_title"=>"dogapi test",
  "width"=>1024,
  "height"=>768,
  "id"=>6334,
  "widgets"=>
   [{"url"=>"http://path/to/image.jpg",
     "height"=>20,
     "width"=>32,
     "y"=>7,
     "x"=>32,
     "type"=>"image"}]}]
{
    "board_title": "dogapi test", 
    "height": 768, 
    "id": 6334, 
    "widgets": [
        {
            "height": 20, 
            "type": "image", 
            "url": "http://path/to/image.jpg", 
            "width": 32, 
            "x": 32, 
            "y": 7
        }
    ], 
    "width": 1024
}

Share a Screenboard

Share an existing screenboard's with a public URL.

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

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

board_id = 6334
api.share_screenboard(board_id)
require 'rubygems'
require 'dogapi'

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

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

board_id = '6334'
dog.share_screenboard(board_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
board_id=6334

curl -X GET \
"https://app.datadoghq.com/api/v1/screen/share/${board_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    "board_id": 6334,
    "public_url": "https://p.datadoghq.com/sb/20756e0cd4"
}
["200",
 {"board_id"=>6334, "public_url"=>"https://p.datadoghq.com/sb/20756e0cd4"}]
{
    "board_id": 6334, 
    "public_url": "https://p.datadoghq.com/sb/20756e0cd4"
}

Tags

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

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

Get Tags

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

Arguments
  • source [optional, default=None]
    Only show tags from a particular source. Otherwise shows all tags.
Signature
GET /api/v1/tags/hosts
Example Request
require 'rubygems'
require 'dogapi'

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

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

dog.all_tags()
from dogapi import dog_http_api as api

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

api.all_tags()
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl "https://app.datadoghq.com/api/v1/tags/hosts?api_key=${api_key}&application_key=${app_key}"
Example Response
["200",
 {"tags"=>
   {"role:web"=>["test.metric.host"],
    "environment:test"=>["test.metric.host"],
    "environment:production"=>["test.another.example.com"],
    "role:webserver"=>["test.another.example.com"]}}]
{'role:database','env:test': ['test.metric.host']}
{
    "tags": {
        "environment:production": [
            "test.another.example.com", 
            "test.host"
        ], 
        "environment:test": [
            "test.metric.host"
        ], 
        "role:database": [
            "test.metric.host"
        ], 
        "role:webserver": [
            "test.another.example.com", 
            "test.host"
        ]
    }
}

Get Host Tags

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

Arguments
  • source [optional, default=None]
    Only show tags from a particular source. Otherwise shows all tags.
  • by_source [optional, default=False]
    Return tags grouped by source.
Signature
GET /api/v1/tags/hosts/:host_id_or_host_name
Example Request
from dogapi import dog_http_api as api

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

# Get tags by host id.
api.host_tags('108816')
require 'rubygems'
require 'dogapi'

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

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

dog.host_tags('108816')
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
host_id=111892

curl "https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
['role:database','env:test']
["200", {"tags"=>["role:web", "environment:test"]}]
{
    "tags": [
        "role:database", 
        "environment:test"
    ]
}

Add Tags to a Host

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

Arguments
  • tags [required]
    A list of tags to apply to the host
  • source [optional, default=users]
    The source of the tags (e.g. chef, puppet).
Signature
POST /api/v1/tags/hosts/:host_id_or_host_name
Example Request
from dogapi import dog_http_api as api

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

api.add_tags('108816', ['role:webserver', 'env:production'])
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
host_id=111892

curl  -X POST -H "Content-type: application/json" \
-d '{
      "tags" : ["environment:production", "role:webserver"]
    }' \
"https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
require 'rubygems'
require 'dogapi'

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

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

dog.add_tags(host_id, ["role:database", "environment:production"])
Example Response
['role:webserver','env:production']
{
    "host": "test.host", 
    "tags": [
        "role:database", 
        "environment:test"
    ]
}
["201",
 {"host"=>"test.metric.host",
  "tags"=>
   ["environment:production",
    "role:web",
    "role:database",
    "environment:test"]}]

Update Host Tags

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

Arguments
  • tags [required]
    A list of tags
  • source [optional, default=users]
    The source of the tags (e.g. chef, puppet).
Signature
PUT /api/v1/tags/hosts/:host_id_or_host_name
Example Request
from dogapi import dog_http_api as api

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

api.change_tags('108816', ['role:database', 'environment:test'])
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
host_id=111892

curl -X PUT -H "Content-type: application/json" \
-d '{
      "tags" : ["environment:production", "role:webserver"]
    }' \
"https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
require 'rubygems'
require 'dogapi'

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

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

dog.update_tags(host_id, ["role:web", "environment:test"])
Example Response
['role:database','env:test']
{
    "host": "test.host", 
    "tags": [
        "environment:production", 
        "role:webserver"
    ]
}
["201", {"host"=>"test.metric.host", "tags"=>["role:web", "environment:test"]}]

Remove Host Tags

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

Arguments
  • source [optional, default=users]
    The source of the tags (e.g. chef, puppet).
Signature
DELETE /api/v1/tags/hosts/:host_id_or_host_name
Example Request
from dogapi import dog_http_api as api

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

# Get tags by host name.
api.detach_tags('web.example.com')
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
host_id=111892

curl -X DELETE "https://app.datadoghq.com/api/v1/tags/hosts/${host_id}?api_key=${api_key}&application_key=${app_key}"
require 'rubygems'
require 'dogapi'

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

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

dog.detach_tags(host_id)
Example Response
This end point does not return JSON on successful requests.

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

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

Search queries allow for limited faceting. Available facets are:

  • hosts
  • metrics

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

Un-faceted queries are of the form:

query_string

Faceted queries are of the form:

facet:query_string
Signature
GET /api/v1/search
Example Request
from dogapi import dog_http_api as api

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

# Search by `host` facet.
api.search("hosts:database")

# Search by `metric` facet.
api.search("metrics:system")

# Search all facets.
api.search("test")
require 'rubygems'
require 'dogapi'

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

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

# Search by `host` facet.
dog.search("hosts:database")

# Search by `metric` facet.
dog.search("metrics:system")

# Search all facets.
dog.search("test")
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -G "https://app.datadoghq.com/api/v1/search" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "q=test"
Example Response
{'hosts': ['test.metric.host', 'test.tag.host'],
 'metrics': ['test.metric.metric', 'test.tag.metric']}
["200",
 {"results"=>
   {"metrics"=>["test.metric"],
    "hosts"=>
     ["test.another.example.com",
      "test.example.com",
      "test.host",
      "test.metric.host",
      "test.tag.host"]}}]
{
    "results": {
        "hosts": [
            "test.another.example.com", 
            "test.example.com", 
            "test.host", 
            "test.metric.host", 
            "test.tag.host"
        ], 
        "metrics": [
            "test.metric"
        ]
    }
}

Comments

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

Create a comment

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

Arguments
  • message [required]
    The comment text.
  • handle [optional, default=application key owner]
    The handle of the user making the comment.
  • related_event_id [optional, default=None]
    The id of another comment or event to reply to
Signature
POST api/v1/comments
Example Request
from dogapi import dog_http_api as api

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

# Start a new discussion.
api.comment('matt@example.com', 'Should we use COBOL or Fortran?')

# Reply to a discussion.
api.comment('joe@example.com', 'Smalltalk?', related_event_id=1234)
require 'rubygems'
require 'dogapi'

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

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

# Make a comment.
dog.comment("I have something to say.")
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl  -X POST -H "Content-type: application/json" \
-d '{
        "message" : "There is a problem with the database."
    }' \
"https://app.datadoghq.com/api/v1/comments?api_key=${api_key}&application_key=${app_key}"
Example Response
123482347822
["200",
 {"comment"=>
   {"url"=>"/event/jump_to?event_id=1382579089039712607",
    "resource"=>"/api/v1/comments/1382579089039712607",
    "message"=>"I have something to say.",
    "handle"=>"mattp+org-carlotest141@datadoghq.com",
    "id"=>1382579089039712607}}]
{
    "comment": {
        "handle": "mattp+org-carlotest141@datadoghq.com", 
        "id": 1382561676571697516, 
        "message": "There is a problem with the database.", 
        "resource": "/api/v1/comments/1382561676571697516", 
        "url": "/event/jump_to?event_id=1382561676571697516"
    }
}

Edit a Comment

Arguments
  • message [optional, default=original message]
    The comment text.
  • handle [optional, default=application key owner]
    The handle of the user making the comment.
Signature
PUT api/v1/comments/:comment_id
Example Request
from dogapi import dog_http_api as api

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

# Edit a comment.
comment_id = 123482347822
api.comment('matt@example.com', 'I think differently now.', comment_id = 12345)
require 'rubygems'
require 'dogapi'

api_key='9775a026f1ca7d1c6c5af9d94d9595a4'
app_key='87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
comment_id="1382579089039712607"

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

# Update a comment.
dog.update_comment(comment_id, :message => "I've changed my mind again")
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
comment_id=1382557387240472966

curl -X PUT -H "Content-type: application/json" \
-d '{
        "message" : "Actually, I am changing my mind."
    }' \
"https://app.datadoghq.com/api/v1/comments/${comment_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
123482347822
["200",
 {"comment"=>
   {"url"=>"/event/jump_to?event_id=1382579089039712607",
    "resource"=>"/api/v1/comments/1382579089039712607",
    "message"=>"I've changed my mind again",
    "handle"=>"mattp+org-carlotest141@datadoghq.com",
    "id"=>1382579089039712607}}]
{
    "comment": {
        "handle": "mattp+org-carlotest141@datadoghq.com", 
        "id": 1382557387240472966, 
        "message": "Actually, I am changing my mind.", 
        "resource": "/api/v1/comments/1382557387240472966", 
        "url": "/event/jump_to?event_id=1382557387240472966"
    }
}

Delete a Comment

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

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

api.delete_comment(123412345)
require 'rubygems'
require 'dogapi'

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

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

dog.delete_comment("1378619807595725030")
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
comment_id=1382559936236196216

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

Alerts

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

Create an alert

Arguments
  • query [required]
    The metric query to alert on. The syntax is:
    time_aggr(time_window):space_aggr:metric_name{tags} [by {tag_key}] operator #
    The items in square brackets are optional. All other delimiters and punctuations are required as written. The accepted arguments for each parameter are as follows:
    • time_aggr avg, sum, max, or min
    • time_window last_#m (5, 10, 15, or 30), last_#h (1, 2, or 4), or last_1d
    • space_aggr avg, sum, min, or max
    • tags one or more tags (comma-separated), or *
    • tag_key a 'key' in key:value tag syntax; defines a separate alert for each tag in the group (multi-alert)
    • operator <, <=, >, >=, ==, or !=
    • # an integer or decimal number used to set the threshold
  • name [optional, default=dynamic, based on query]
    The name of the alert.
  • message [optional, default=None]
    A message to include with notifications for this alert. Email notifications can be sent to specific users by using the same '@username' notation as events.
  • silenced [optional, default=False]
    Whether the alert should notify by email and in the event stream. An alert with 'silenced' set to 'True' is effectively muted. The alert will continue to detect state changes, but they will only be visible on the alert list page.
  • notify_no_data [optional, default=None]
    Set to 'True' to send a notification if data is missing.
  • timeout_h [optional, default=None]
    Set this value to an integer to automatically resolve the alert after the specified number of hours. For some metrics that report periodically across different tags, it may make sense to set associated alerts to auto-resolve. For instance, if a counter metric only reports when an error occurs, the triggered alert will never resolve because the metric doesn't report 0 errors.
Signature
POST api/v1/alert
Example Request
from dogapi import dog_http_api as api

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

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

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

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

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

curl -X POST -H "Content-type: application/json" \
-d '{
      "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "name": "Bytes received on host0",
      "message": "We may need to add web hosts if this is consistently high."
    }' \
    "https://app.datadoghq.com/api/v1/alert?api_key=${api_key}&application_key=${app_key}"
Example Response
525
["201",
 {"notify_no_data"=>false,
  "silenced"=>false,
  "creator"=>3658,
  "message"=>"We may need to add web hosts if this is consistently high.",
  "id"=>537,
  "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "name"=>"Bytes received on host0",
  "state"=>"OK",
  "event_object"=>"e7ac36c6531ccfa9e39c8988b0f28bdb"}]
{
    "creator": 3658, 
    "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb", 
    "id": 512, 
    "message": "We may need to add web hosts if this is consistently high.", 
    "name": "Bytes received on host0", 
    "notify_no_data": false, 
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", 
    "silenced": false, 
    "state": "OK"
}

Get an alert's details

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

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

# Get an alert's details
api.get_alert(525)
require 'rubygems'
require 'dogapi'

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

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

# Get an alert's details
dog.get_alert(537)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
alert_id=512

curl -G "https://app.datadoghq.com/api/v1/alert/${alert_id}" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"
Example Response
{'creator': 3658,
 'event_object': 'e7ac36c6531ccfa9e39c8988b0f28bdb',
 'id': 525,
 'message': 'We may need to add web hosts if this is consistently high.',
 'name': 'Bytes received on host0',
 'notify_no_data': False,
 'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
 'silenced': False,
 'state': 'OK'}
["200",
 {"message"=>"We may need to add web hosts if this is consistently high.",
  "creator"=>3658,
  "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "id"=>537,
  "notify_no_data"=>false,
  "event_object"=>"e7ac36c6531ccfa9e39c8988b0f28bdb",
  "silenced"=>false,
  "name"=>"Bytes received on host0",
  "state"=>"OK"}]
{
    "creator": 3658, 
    "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb", 
    "id": 512, 
    "message": "We may need to add web hosts if this is consistently high.", 
    "name": "Bytes received on host0", 
    "notify_no_data": false, 
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", 
    "silenced": false, 
    "state": "OK"
}

Edit an alert

Arguments
  • query [required]
    The metric query to alert on.
  • name [optional, default=dynamic, based on query]
    The name of the alert.
  • message [optional, default=None]
    A message to include with notifications for this alert. Email notifications can be sent to specific users by using the same '@username' notation as events.
  • silenced [optional, default=False]
    Whether the alert should notify by email and in the event stream. An alert with 'silenced' set to True is effectively muted. The alert will continue to detect state changes, but they will only be visible on the alert list page.
  • silenced_timeout_ts [optional, default=None]
    An alert with 'silenced' set to True can have a silenced timeout timestamp. When the silenced timeout timestamp expires, the alert gets unmuted.
Signature
PUT api/v1/alert/:alert_id
Example Request
from dogapi import dog_http_api as api

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

# Edit an existing alert
api.update_alert(525, "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", "Bytes received on host0", "We may need to add web hosts if this is consistently high.", silenced=True, silenced_timeout_ts=1401833000)
require 'rubygems'
require 'dogapi'

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

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

# Edit an existing alert
dog.update_alert(537, "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", :message => "Bytes received on host0", :name => "We may need to add web hosts if this is consistently high.", :silenced => true, :silenced_timeout_ts => 1401833000)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
alert_id=512

curl -X PUT -H "Content-type: application/json" \
-d '{
      "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
      "name": "Bytes received on host0",
      "message": "We may need to add web hosts if this is consistently high.",
      "silenced": true,
      "silenced_timeout_ts": 1401833000
    }' \
    "https://app.datadoghq.com/api/v1/alert/${alert_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
525
["200",
 {"query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "silenced"=>true,
  "silenced_timeout_ts"=>1401833000,
  "message"=>"Bytes received on host0",
  "name"=>"We may need to add web hosts if this is consistently high.",
  "notify_no_data"=>false,
  "state"=>"OK",
  "event_object"=>"0af4b37f8edaf5c810547a35e2e23ea1",
  "id"=>537,
  "creator"=>3658}]
{
    "creator": 3658,
    "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb",
    "id": 512,
    "message": "We may need to add web hosts if this is consistently high.",
    "name": "Bytes received on host0",
    "notify_no_data": false,
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
    "silenced": true,
    "silenced_timeout_ts": 1401833000,
    "state": "OK"
}

Delete an alert

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

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

# Delete an alert
api.delete_alert(525)
require 'rubygems'
require 'dogapi'

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

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

# Delete an alert
dog.delete_alert(537)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
alert_id=512

curl -X DELETE "https://app.datadoghq.com/api/v1/alert/${alert_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{'creator': 3658,
 'event_object': 'e7ac36c6531ccfa9e39c8988b0f28bdb',
 'message': 'We may need to add web hosts if this is consistently high.',
 'name': 'Bytes received on host0',
 'notify_no_data': False,
 'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
 'silenced': True,
 'state': 'OK'}
["200",
 {"creator"=>3658,
  "name"=>"We may need to add web hosts if this is consistently high.",
  "event_object"=>"0af4b37f8edaf5c810547a35e2e23ea1",
  "notify_no_data"=>false,
  "query"=>"avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "silenced"=>true,
  "message"=>"Bytes received on host0",
  "state"=>"OK"}]
{
    "creator": 3658, 
    "event_object": "e7ac36c6531ccfa9e39c8988b0f28bdb", 
    "message": "We may need to add web hosts if this is consistently high.", 
    "name": "Bytes received on host0", 
    "notify_no_data": false, 
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100", 
    "silenced": true, 
    "state": "OK"
}

Get all alert details

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

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

# Get all alert details
api.get_all_alerts()
require 'rubygems'
require 'dogapi'

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

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

# Get all alert details
dog.get_all_alerts()
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -G "https://app.datadoghq.com/api/v1/alert" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"
Example Response
[{'creator': 3658,
  'event_object': 'e7ac36c6531ccfa9e39c8988b0f28bdb',
  'id': 522,
  'message': 'We may need to add web hosts if this is consistently high.',
  'name': 'Bytes received on host0',
  'notify_no_data': False,
  'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
  'silenced': False,
  'state': 'Alert'}]
["200",
 {"alerts"=>
   [{"id"=>273,
     "state"=>"No Data",
     "silenced"=>false,
     "message"=>" @pagerduty",
     "query"=>"avg(last_10m):max:system.load.5{host:alexsolo} > 6",
     "name"=>"Load AVG on host:alexsolo",
     "event_object"=>"f64854a9d66cd1eea9d77ec82588ff91",
     "notify_no_data"=>false,
     "creator"=>3658}]}]
{
    "alerts": [
        {
            "creator": 3658, 
            "event_object": "f64854a9d66cd1eea9d77ec82588ff91", 
            "id": 273, 
            "message": " @pagerduty", 
            "name": "Load AVG on host:alexsolo", 
            "notify_no_data": false, 
            "query": "avg(last_10m):max:system.load.5{host:alexsolo} > 6", 
            "silenced": false, 
            "state": "OK"
        }, 
        {
            "creator": 3658, 
            "event_object": "f64854a9d66cd1eea9d77ec82588ff91", 
            "id": 274, 
            "message": " @pagerduty", 
            "name": "Load AVG on host:alexsolo", 
            "notify_no_data": false, 
            "query": "avg(last_1m):max:system.load.5{host:alexsolo} > 6", 
            "silenced": false, 
            "state": "OK"
        }
    ]
}

Mute all alerting

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

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

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

# Mute all alerts
api.mute_alerts()
require 'rubygems'
require 'dogapi'

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

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

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

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

Unmute all alerting

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

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

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

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

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

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

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

Users

You can invite users to join DataDog using the API.

Invite Users

Arguments
  • emails [required]
    A list of email addresses to send an invite to.
Signature
POST api/v1/invite_users
Example Request
from dogapi import dog_http_api as api

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

# Send invites
api.invite(["jack@example.com", "jill@example.com"])
require 'rubygems'
require 'dogapi'

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

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

dog.invite(["jack@example.com", "jill@example.com"])
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
alert_id=512

curl -X POST -H "Content-type: application/json" \
-d '{
      "emails": ["jack@example.com", "jill@example.com"]
    }' \
    "https://app.datadoghq.com/api/v1/invite_users?api_key=${api_key}&application_key=${app_key}"
Example Response
["jack@example.com", "jill@example.com"]
["200", 
    {"emails"=>["jack@example.com", "jill@example.com"]}
]
{"emails": ["jack@example.com", "jill@example.com"]}

Graphs

You can take graph snapshots using the API.

Graph Snapshot

Arguments
  • metric_query [required]
    The metric query.
  • start [required]
    The POSIX timestamp of the start of the query.
  • end [required]
    The POSIX timestamp of the end of the query.
  • event_query [optional, default=None]
    A query that will add event bands to the graph.
Signature
GET api/v1/graph/snapshot
Example Request
import time
from dogapi import dog_http_api as api

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

# Take a graph snapshot
end = int(time.time())
start = end - (60 * 60)
api.graph_snapshot("system.load.1{*}", start, end)
require 'rubygems'
require 'dogapi'

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

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

end_ts = Time.now().to_i
start_ts = end_ts - (60 * 60)
dog.graph_snapshot("system.load.1{*}", start_ts, end_ts)
curl -G -H "Content-type: application/json" \
    -d "metric_query=system.load.1{*}" \
    -d "start=1346272158" \
    -d "end=1346274158" \
    -d "api_key=9775a026f1ca7d1c6c5af9d94d9595a4" \
    -d "application_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" \
    'https://app.datadoghq.com/api/v1/graph/snapshot'
Example Response
{'event_query': 'None',
 'metric_query': 'system.load.1{*}',
 'snapshot_url': 'https://s3.amazonaws.com/dd-snapshots-prod/org_1499/2013-07-19/2459d291fc021c84f66aac3a87251b6c92b589da.png'}
["200",
 {"metric_query"=>"system.load.1{*}",
  "snapshot_url"=>
   "https://s3.amazonaws.com/dd-snapshots-prod/org_1499/2013-07-19/7f6dd29198ce0872a6fdfab33f534ef8d64a23ea.png"}]
{
    "metric_query": "system.load.1{*}", 
    "snapshot_url": "https://s3.amazonaws.com/dd-snapshots-prod/org_1499/2013-07-19/53fd79f024e7796f4ca399f1d90adf3cf95a9bb8.png"
}

Troubleshooting

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

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

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

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


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