New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Overview

This section details Datadog’s HTTP API for getting data in and out of Datadog.

To get started on Datadog HTTP API, use our Datadog Postman collection

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.

Note: cURL code examples assume usage of BASH and GNU coreutils. On macOS you can install coreutils via the Homebrew package manager: brew install coreutils

SIGNATURE

There are many client libraries that wrap the Datadog API.

SIGNATURE

  • If you are on the Datadog US site: https://api.datadoghq.com/api/
  • If you are on the Datadog EU site: https://api.datadoghq.eu/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.

Manage your account’s API and application keys.

EXAMPLE

from datadog import initialize, api

options = {'api_key': '<YOUR_API_KEY>',
           'app_key': '<YOUR_APP_KEY>'}

initialize(**options)
require 'rubygems'
require 'dogapi'

dog = Dogapi::Client.new('<YOUR_API_KEY>', '<YOUR_APP_KEY>')


curl "https://api.datadoghq.com/api/v1/validate?api_key=<YOUR_API_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. Note: When using libraries, some errors may throw exceptions rather than return JSON objects.

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 indicates success and the response body contains 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
  • 413 Payload Too Large
  • 422 Unprocessable
  • 429 Too Many Requests
  • 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.'
  ]
}

Rate limiting

Some of the API endpoints are rate limited. Once you exceed a certain number of requests in a certain time period we return an error.

For rate limited API endpoints we return headers so you can know how close you are to your limit. If you exceed your limit, review these headers to determine when you are able to try again.

Rate limits can be increased from defaults by contacting the Datadog support team.

Regarding API rate limit policy:

  • Datadog does not rate limit on data point/metric submission (see metrics section for more info on how metric submission rate is handled). Limits encounter is dependent on the quantity of custom metrics based on your agreement.
  • The rate limit for metric retrieval is 100 per hour per organization.
  • The rate limit for event submission is 1000 per aggregate per day per organization. An aggregate is a group of similar events.
  • The rate limit for the query_batch API and Log Query API call is 300 per hour per organization. This can be extended on demand.
  • The rate limit for the graph_snapshot API call is 60 per hour per organization. This can be extended on demand.
  • The rate limit for Log Configuration API is 6000 per minute per organization. This can be extended on demand.
Rate Limit Headers
  • X-RateLimit-Limit number of requests allowed in a time period
  • X-RateLimit-Period length of time in seconds for resets (calendar aligned)
  • X-RateLimit-Remaining number of allowed requests left in current time period
  • X-RateLimit-Reset time in seconds until next reset

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 the Datadog 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 2>&1 | grep -i '< date'

This outputs the current system’s date, then makes a request to an API endpoint to grab the date on the Datadog 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 results in a 202 ‘success’ but no event showing up. Having an invalid source_type_name don’t prevent the event from showing up, but that field is dropped upon submission.

Note: Datadog API keys are case-sensitive. All your JSON attributes for POST endpoints should be in lowercase.

Service Checks

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

Service check messages are limited to 500 characters. If a check is posted with a message containing more than 500 characters, only the 500 first characters are displayed.

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:

    • 0 : OK
    • 1 : WARNING
    • 2 : CRITICAL
    • 3 : UNKNOWN
  • tags [required]: A list of key:val tags for this check

  • timestamp [optional]: POSIX timestamp of the event.

  • message [optional]: A description of why this status occurred

Signature

POST /v1/check_run

Example Request
from datadog import initialize, api
from datadog.api.constants import CheckStatus

options = {'api_key': '<YOUR_API_KEY>',
           'app_key': '<YOUR_APP_KEY>'}

initialize(**options)

check = 'app.ok'
host = 'app1'
status = CheckStatus.OK  # equals 0
tags = ['env:test']

api.ServiceCheck.check(check=check, host_name=host, status=status, message='Response: 200 OK', tags=tags)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# submitting a check doesn't require an app_key
dog = Dogapi::Client.new(api_key)

dog.service_check('app.is_ok', 'app1', 0, :message => 'Response: 200 OK', :tags => ['env:test'])
currenttime=$(date +%s)

curl  -X POST -H "Content-type: application/json" \
-d "{
      \"check\": \"app.is_ok\",
      \"host_name\": \"app1\",
      \"timestamp\": $currenttime,
      \"status\": 0,
      \"tags\": [\"env:test\"]
}" \
"https://api.datadoghq.com/api/v1/check_run?api_key=<YOUR_API_KEY>"
Example Response
{
    'status': 'ok'
}
["202", {
    "status" => "ok"
}]

{
  "status": "ok"
}

Comments

Comments are how discussion happens on Datadog. Create, edit, delete and reply to comments.

Create A Comment

Comments are essentially special forms of events that appear in the event 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 /v1/comments

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Start a new discussion.
# Include a handle like this
api.Comment.create(
    handle='matt@example.com',
    message='Should we use COBOL or Fortran!'
)

# Or set it to None
# and the handle defaults
# 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 = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Make a comment.
dog.comment("I have something to say.")
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl  -X POST -H "Content-type: application/json" \
-d '{
        "message" : "There is a problem with the database."
}' \
"https://api.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 /v1/comments/<COMMENT_ID>

from datadog import initialize, api
from time import sleep

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Edit a comment.
newcomment = api.Comment.create(
    message='Should we use COBOL or Fortran or Widgets?'
)

sleep(1)

api.Comment.update(
    newcomment['comment']['id'],
    message='I think differently now!'
)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'
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=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
comment_id=<COMMENT_ID>

# Create a comment to edit. Use jq (http://stedolan.github.io/jq/download/) to get the comment id.
comment_id=$(curl -X POST -H "Content-type: application/json" -d '{"message" : "This comment was submitted and will be edited by the api."}' "https://api.datadoghq.com/api/v1/comments?api_key=${api_key}&application_key=${app_key}" | jq -r '.comment.resource|ltrimstr("/api/v1/comments/")')

curl -X PUT -H "Content-type: application/json" \
-d '{
        "message" : "Actually, I am changing my mind."
}' \
"https://api.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"
  }
}

Dashboards

This new endpoint unifies screenboard and timeboard APIs to allow you to manage all of your dashboards using a single format. Documentation for old endpoints is available here:

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

Create a Dashboard

Arguments
  • title [required]: Title of the dashboard.
  • widgets [required]: List of widgets to display on the dashboard. Widget definitions follow this form:
  • layout_type [required]: Layout type of the dashboard. Available values are: ordered (previous timeboard) or free (previous screenboard layout)
  • description [optional, default=None]: Description of the dashboard.
  • is_read_only [optional, default=False]: Whether this dashboard is read-only. If True, only the author and admins can make changes to it.
  • notify_list [optional, default=None]: List of handles of users to notify when changes are made to this dashboard.
  • template_variables [optional, default=None]: List of template variables for this dashboard. Template variable definitions follow this form:
    • name [required]: The name of the variable.
    • default [optional, default=None]: The default value for the template variable on dashboard load.
    • prefix [optional, default=None]: The tag prefix associated with the variable. Only tags with this prefix appear in the variable dropdown.
Signature

POST /v1/dashboard

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

title = 'Average Memory Free Shell'
widgets = [{
    'definition': {
        'type': 'timeseries',
        'requests': [
            {'q': 'avg:system.mem.free{*}'}
        ],
        'title': 'Average Memory Free'
    }
}]
layout_type = 'ordered'
description = 'A dashboard with memory info.'
is_read_only = True
notify_list = ['user@domain.com']
template_variables = [{
    'name': 'host1',
    'prefix': 'host',
    'default': 'my-host'
}]
api.Dashboard.create(title=title,
                     widgets=widgets,
                     layout_type=layout_type,
                     description=description,
                     is_read_only=is_read_only,
                     notify_list=notify_list,
                     template_variables=template_variables)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Create a dashboard.
title = 'Average Memory Free Shell'
widgets = [{
    'definition': {
        'type' => 'timeseries',
        'requests' => [
            {'q' => 'avg:system.mem.free{*}'}
        ],
        'title' => 'Average Memory Free'
    }
}]
layout_type = 'ordered'
description = 'A dashboard with memory info.'
is_read_only = true
notify_list = ['user@domain.com']
template_variables = [{
    'name' => 'host1',
    'prefix' => 'host',
    'default' => 'my-host'
}]

dog.create_board(title, widgets, layout_type, {
    'description' => description,
    'is_read_only' => is_read_only,
    'notify_list' => notify_list,
    'template_variables' => template_variables
    })
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl  -X POST -H "Content-type: application/json" \
-d '{
      "title" : "Average Memory Free Shell",
      "widgets" : [{
          "definition": {
              "type": "timeseries",
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ],
              "title": "Average Memory Free"
          }
      }],
      "layout_type": "ordered",
      "description" : "A dashboard with memory info.",
      "is_read_only": true,
      "notify_list": ["user@domain.com"],
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "my-host"
      }]
}' \
"https://api.datadoghq.com/api/v1/dashboard?api_key=${api_key}&application_key=${app_key}"
Example Response
{
   'notify_list':[
        'user@domain.com'
   ],
   'description':'A dashboard with memory info.',
   'template_variables':[
      {
         'default':'my-host',
         'prefix':'host',
         'name':'host1'
      }
   ],
   'is_read_only':True,
   'id':'qc9-tuk-9kv',
   'title':'Average Memory Free Shell',
   'url':'/dashboard/qc9-tuk-9kv/average-memory-free-shell',
   'created_at':'2019-02-05T01:20:56.323548+00:00',
   'modified_at':'2019-02-05T01:20:56.323548+00:00',
   'author_handle':'user@domain.com',
   'widgets':[
      {
         'definition':{
            'requests':[
               {
                  'q':'avg:system.mem.free{*}'
               }
            ],
            'type':'timeseries',
            'title':'Average Memory Free'
         },
         'id':2252428653625902
      }
   ],
   'layout_type':'ordered'
}
[
   "200",
   {
      "notify_list" => ["user@domain.com"],
      "description" => nil,
      "template_variables" => nil,
      "is_read_only" => true,
      "id" => "qc9-tuk-9kv",
      "title" => "Average Memory Free Shell",
      "url" => "/dashboard/qc9-tuk-9kv/average-memory-free-shell",
      "created_at" => "2019-02-05T01:35:46.388000+00:00",
      "modified_at" => "2019-02-05T01:35:46.388000+00:00",
      "author_handle" => "user@domain.com",
      "widgets" => [
         {
            "definition" => {
               "requests" => [
                   { "q" => "avg:system.mem.free{*}"}
               ],
               "type" => "timeseries",
               "title" => "Average Memory Free"
            },
            "id" => 2252428653625902
         }
      ],
      "layout_type" => "ordered"
   }
]
{
    "notify_list": [
        "user@domain.com"
    ],
    "description": "A dashboard with memory info.",
    "template_variables": [
        {
            "default": "my-host",
            "prefix": "host",
            "name": "host1"
        }
    ],
    "is_read_only": true,
    "id": "qc9-tuk-9kv",
    "title": "Average Memory Free Shell",
    "url": "/dashboard/qc9-tuk-9kv/average-memory-free-shell",
    "created_at": "2019-02-05T01:06:36.636295+00:00",
    "modified_at": "2019-02-05T01:06:36.636295+00:00",
    "author_handle": "user@domain.com",
    "widgets": [
        {
            "definition": {
                "requests": [
                    {
                        "q": "avg:system.mem.free{*}"
                    }
                ],
                "type": "timeseries",
                "title": "Average Memory Free"
            },
            "id": 2252428653625902
        }
    ],
    "layout_type": "ordered"
}

Update a Dashboard

Arguments
  • title [required]: Title of the dashboard.
  • widgets [required]: List of widgets to display on the dashboard. Widget definitions follow this form:
  • layout_type [required]: Layout type of the dashboard. Available values are: ordered (previous timeboard) or free (previous screenboard layout)
  • description [optional, default=None]: Description of the dashboard.
  • is_read_only [optional, default=False]: Whether this dashboard is read-only. If True, only the author and admins can make changes to it.
  • notify_list [optional, default=None]: List of handles of users to notify when changes are made to this dashboard.
  • template_variables [optional, default=None]: List of template variables for this dashboard. Template variable definitions follow this form:
    • name [required]: The name of the variable.
    • default [optional, default=None]: The default value for the template variable on dashboard load.
    • prefix [optional, default=None]: The tag prefix associated with the variable. Only tags with this prefix appear in the variable dropdown.
Signature

PUT /v1/dashboard/<DASHBOARD_ID>

Example Request
from datadog import initialize, api

options = {'api_key': '<YOUR_API_KEY>',
           'app_key': '<YOUR_APP_KEY>'}

initialize(**options)

dashboard_id = '<DASHBOARD_ID>'

title = 'Sum of Memory Free'
widgets = [{
    'definition': {
        'type': 'timeseries',
        'requests': [
            {'q': 'sum:system.mem.free{*}'}
        ],
        'title': 'Sum Memory Free Shell'
    }
}]
layout_type = 'ordered'
description = 'An updated dashboard with memory info.'
is_read_only = True
notify_list = ['user@domain.com']
template_variables = [{
    'name': 'host1',
    'prefix': 'host',
    'default': 'my-host'
}]
api.Dashboard.update(dashboard_id,
                     title=title,
                     widgets=widgets,
                     layout_type=layout_type,
                     description=description,
                     is_read_only=is_read_only,
                     notify_list=notify_list,
                     template_variables=template_variables)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dashboard_id = '<DASHBOARD_ID>'

title = 'Sum of Memory Free'
widgets = [{
    'definition': {
        'type' => 'timeseries',
        'requests' => [
            {'q' => 'sum:system.mem.free{*}'}
        ],
        'title' => 'Sum Memory Free Shell'
    }
}]
layout_type = 'ordered'
description = 'An updated dashboard with memory info.'
is_read_only = true
notify_list = ['user@domain.com']
template_variables = [{
    'name' => 'host1',
    'prefix' => 'host',
    'default' => 'my-host'
}]

dog.update_board(dashboard_id, title, widgets, layout_type, {
    'description' => description,
    'is_read_only' => is_read_only,
    'notify_list' => notify_list,
    'template_variables' => template_variables
    })
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
dashboard_id="<DASHBOARD_ID>"

curl  -X PUT -H "Content-type: application/json" \
-d '{
      "title" : "Sum of Memory Free",
      "widgets" : [{
          "definition": {
              "type": "timeseries",
              "requests": [
                  {"q": "sum:system.mem.free{*}"}
              ],
              "title": "Sum Memory Free Shell"
          }
      }],
      "layout_type": "ordered",
      "description" : "An updated dashboard with memory info.",
      "is_read_only": true,
      "notify_list": ["user@domain.com"],
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "my-host"
      }]
}' \
"https://api.datadoghq.com/api/v1/dashboard/${dashboard_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
   'notify_list':[
        'user@domain.com'
   ],
   'description':'An updated dashboard with memory info.',
   'template_variables':[
      {
         'default':'my-host',
         'prefix':'host',
         'name':'host1'
      }
   ],
   'is_read_only':True,
   'id':'qc9-tuk-9kv',
   'title':'Sum of Memory Free',
   'url':'/dashboard/qc9-tuk-9kv/sum-of-memory-free',
   'created_at':'2019-02-05T01:06:36.636295+00:00',
   'modified_at':'2019-02-05T02:14:15.769022+00:00',
   'author_handle':'user@domain.com',
   'widgets':[
      {
         'definition':{
            'requests':[
               {
                  'q':'sum:system.mem.free{*}'
               }
            ],
            'type':'timeseries',
            'title':'Sum Memory Free Shell'
         },
         'id':6744688099018785
      }
   ],
   'layout_type':'ordered'
}
[
   "200",
   {
      "notify_list" => ["user@domain.com"],
      "description" => nil,
      "template_variables" => nil,
      "is_read_only" => false,
      "id" => "qc9-tuk-9kv",
      "title" => "Sum of Memory Free",
      "url" => "/dashboard/qc9-tuk-9kv/sum-of-memory-free",
      "created_at" => "2019-02-05T01:06:36.636295+00:00",
      "modified_at" => "2019-02-05T02:19:06.792555+00:00",
      "author_handle" => "user@domain.com",
      "widgets" => [
         {
            "definition" => {
               "requests" => [
                  {
                     "q" => "sum:system.mem.free{*}"
                  }
               ],
               "type" => "timeseries",
               "title" => "Sum Memory Free Shell"
            },
            "id" => 7763291144447019
         }
      ],
      "layout_type" => "ordered"
   }
]
{
    "notify_list": ["user@domain.com"],
    "description": "An updated dashboard with memory info.",
    "template_variables": [
        {
            "default": "my-host",
            "prefix": "host",
            "name": "host1"
        }
    ],
    "is_read_only": true,
    "id": "qc9-tuk-9kv",
    "title": "Sum of Memory Free",
    "url": "/dashboard/qc9-tuk-9kv/sum-of-memory-free",
    "created_at": "2019-02-05T01:06:36.636295+00:00",
    "modified_at": "2019-02-05T02:08:57.399410+00:00",
    "author_handle": "user@domain.com",
    "widgets": [
        {
            "definition": {
                "requests": [
                    {
                        "q": "sum:system.mem.free{*}"
                    }
                ],
                "type": "timeseries",
                "title": "Sum Memory Free Shell"
            },
            "id": 6979333833881176
        }
    ],
    "layout_type": "ordered"
}

Delete a Dashboard

Delete an existing dashboard.

Arguments

This endpoint takes no JSON arguments.

Signature

DELETE /v1/dashboard/<DASHBOARD_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

dashboard_id = '<DASHBOARD_ID>'

api.Dashboard.delete(dashboard_id)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dashboard_id = '<DASHBOARD_ID>'
dog.delete_board(dashboard_id)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
dashboard_id="<DASHBOARD_ID>"

curl -X DELETE "https://api.datadoghq.com/api/v1/dashboard/${dashboard_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'deleted_dashboard_id': 'qc9-tuk-9kv'
}
["200", {"deleted_dashboard_id" => "qc9-tuk-9kv"}]
{
    "deleted_dashboard_id": "qc9-tuk-9kv"
}

Get a Dashboard

Fetch an existing dashboard’s definition.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/dashboard/<DASHBOARD_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

dashboard_id = '<DASHBOARD_ID>'

api.Dashboard.get(dashboard_id)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dashboard_id = '<DASHBOARD_ID>'
dog.get_board(dashboard_id)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
dashboard_id="<DASHBOARD_ID>"

curl "https://api.datadoghq.com/api/v1/dashboard/${dashboard_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
   'notify_list':[
        'user@domain.com'
   ],
   'description':'A dashboard with memory info.',
   'template_variables':[
      {
         'default':'my-host',
         'prefix':'host',
         'name':'host1'
      }
   ],
   'is_read_only':True,
   'id':'qc9-tuk-9kv',
   'title':'Average Memory Free Shell',
   'url':'/dashboard/qc9-tuk-9kv/average-memory-free-shell',
   'created_at':'2019-02-05T01:20:56.323548+00:00',
   'modified_at':'2019-02-05T01:20:56.323548+00:00',
   'author_handle':'user@domain.com',
   'widgets':[
      {
         'definition':{
            'requests':[
               {
                  'q':'avg:system.mem.free{*}'
               }
            ],
            'type':'timeseries',
            'title':'Average Memory Free'
         },
         'id':2252428653625902
      }
   ],
   'layout_type':'ordered'
}
{
    "notify_list": [
        "user@domain.com"
    ],
    "description": "A dashboard with memory info.",
    "template_variables": [
        {
            "default": "my-host",
            "prefix": "host",
            "name": "host1"
        }
    ],
    "is_read_only": true,
    "id": "qc9-tuk-9kv",
    "title": "Average Memory Free Shell",
    "url": "/dashboard/qc9-tuk-9kv/average-memory-free-shell",
    "created_at": "2019-02-05T01:06:36.636295+00:00",
    "modified_at": "2019-02-05T01:06:36.636295+00:00",
    "author_handle": "user@domain.com",
    "widgets": [
        {
            "definition": {
                "requests": [
                    {
                        "q": "avg:system.mem.free{*}"
                    }
                ],
                "type": "timeseries",
                "title": "Average Memory Free"
            },
            "id": 2252428653625902
        }
    ],
    "layout_type": "ordered"
}
{
    "notify_list": [
        "user@domain.com"
    ],
    "description": "A dashboard with memory info.",
    "template_variables": [
        {
            "default": "my-host",
            "prefix": "host",
            "name": "host1"
        }
    ],
    "is_read_only": true,
    "id": "qc9-tuk-9kv",
    "title": "Average Memory Free Shell",
    "url": "/dashboard/qc9-tuk-9kv/average-memory-free-shell",
    "created_at": "2019-02-05T01:06:36.636295+00:00",
    "modified_at": "2019-02-05T01:06:36.636295+00:00",
    "author_handle": "user@domain.com",
    "widgets": [
        {
            "definition": {
                "requests": [
                    {
                        "q": "avg:system.mem.free{*}"
                    }
                ],
                "type": "timeseries",
                "title": "Average Memory Free"
            },
            "id": 2252428653625902
        }
    ],
    "layout_type": "ordered"
}

Get all Dashboards

Fetch all dashboards.

Arguments

This end point takes no JSON arguments.

Signature

GET /v1/dashboard

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.Dashboard.get_all()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dog.get_all_boards()
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl "https://api.datadoghq.com/api/v1/dashboard?api_key=${api_key}&application_key=${app_key}"
Example Response
{
  'dashboards': [{
      'created_at': '2019-02-28T17:12:59.327729+00:00',
      'is_read_only': False,
      'description': 'My Screenboard Description',
      'title': 'My Screenboard',
      'url': '/dashboard/grh-zkj-h2c/my-screenboard',
      'layout_type': 'free',
      'modified_at': '2019-03-13T19:09:40.930616+00:00',
      'author_handle':'user@domain.com',
      'id': 'grh-zkj-h2c'
    },
    {
      'created_at': '2019-02-28T17:45:11.535045+00:00',
      'is_read_only': False,
      'description': 'My Timeboard Description',
      'title': 'My Timeboard',
      'url': '/dashboard/4qf-77b-uhc/my-timeboard',
      'layout_type': 'ordered',
      'modified_at': '2019-03-11T14:22:03.131495+00:00',
      'author_handle':'user@domain.com',
      'id': '4qf-77b-uhc'
    }
  ]
}
{
  "dashboards": [{
    "created_at" => "2019-02-28T17:12:59.327729+00:00",
    "is_read_only" => false,
    "description" => "My Screenboard Description",
    "title" => "My Screenboard",
    "url" => "/dashboard/grh-zkj-h2c/my-screenboard",
    "layout_type" => "free",
    "modified_at" => "2019-03-13T19:09:40.930616+00:00",
    "author_handle": "user@domain.com",
    "id" => "grh-zkj-h2c"
  }, {
    "created_at" => "2019-02-28T17:45:11.535045+00:00",
    "is_read_only" => false,
    "description" => "My Timeboard Description",
    "title" => "My Timeboard",
    "url" => "/dashboard/4qf-77b-uhc/my-timeboard",
    "layout_type" => "ordered",
    "modified_at" => "2019-03-11T14:22:03.131495+00:00",
    "author_handle": "user@domain.com",
    "id" => "4qf-77b-uhc"
  }]
}
{
  "dashboards": [{
      "created_at": "2019-02-28T17:12:59.327729+00:00",
      "is_read_only": false,
      "description": "My Screenboard Description",
      "title": "My Screenboard",
      "url": "/dashboard/grh-zkj-h2c/my-screenboard",
      "layout_type": "free",
      "modified_at": "2019-03-13T19:09:40.930616+00:00",
      "author_handle": "user@domain.com",
      "id": "grh-zkj-h2c"
    },
    {
      "created_at": "2019-02-28T17:45:11.535045+00:00",
      "is_read_only": false,
      "description": "My Timeboard Description",
      "title": "My Timeboard",
      "url": "/dashboard/4qf-77b-uhc/my-timeboard",
      "layout_type": "ordered",
      "modified_at": "2019-03-11T14:22:03.131495+00:00",
      "author_handle": "user@domain.com",
      "id": "4qf-77b-uhc"
    }
  ]
}

Dashboard Lists

Interact with your dashboard lists through the API to make it easier to organize, find, and share all of your dashboards with your team and organization.

Get a Dashboard List

Fetch an existing dashboard list’s definition.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/dashboard/lists/manual/<LIST_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.DashboardList.get(4741)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

result = dog.get_dashboard_list(4741)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X GET \
"https://api.datadoghq.com/api/v1/dashboard/lists/manual/${list_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'name': 'My Dashboard List',
    'created': '2018-03-16T09:44:41.476018+00:00',
    'author': {
        'handle': 'test1@datadoghq.com',
        'name': 'Author Name'
    },
    'dashboards': None,
    'modified': '2018-03-16T09:44:41.476030+00:00',
    'is_favorite': False,
    'dashboard_count': 0,
    'type': 'manual_dashboard_list',
    'id': 4741
}
[
    "200",
    {
        "is_favorite" => false,
        "name" => "My Dashboard List",
        "dashboard_count" => 0,
        "author" => {
            "handle" => "test1@datadoghq.com",
            "name" => "Author Name"
        },
        "created" => "2018-03-16T09:44:41.476018+00:00",
        "type" => "manual_dashboard_list",
        "dashboards" => nil,
        "modified" => "2018-03-16T09:44:41.476030+00:00",
        "id" => 4741
    }
]
{
    "name": "My Dashboard List",
    "created": "2018-03-16T09:44:41.476018+00:00",
    "author": {
        "handle": "test1@datadoghq.com",
        "name": "Author Name"
    },
    "dashboards": None,
    "modified": "2018-03-16T09:44:41.476030+00:00",
    "is_favorite": False,
    "dashboard_count": 0,
    "type": "manual_dashboard_list",
    "id": 4741
}

Get all Dashboard Lists

Fetch all of your existing dashboard list definitions.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/dashboard/lists/manual

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.DashboardList.get_all()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

result = dog.get_all_dashboard_lists()
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X GET \
"https://api.datadoghq.com/api/v1/dashboard/lists/manual?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'dashboard_lists': [
        {
            'name': 'My Dashboard List B',
            'created': '2017-09-14T14:59:59.040891+00:00',
            'author': {
                'handle': 'test1@datadoghq.com',
                'name': 'Author Name'
            },
            'dashboards': None,
            'modified': '2018-03-16T13:03:52.698416+00:00',
            'is_favorite': True,
            'dashboard_count': 22,
            'type': 'manual_dashboard_list',
            'id': 142
        },
        {
            'name': 'My Dashboard List A',
            'created': '2017-11-17T11:17:43.273931+00:00',
            'author': {
                'handle': 'test2@datadoghq.com',
                'name': 'Other Author Name'
            },
            'dashboards': None,
            'modified': '2018-03-16T13:03:43.835281+00:00',
            'is_favorite': False,
            'dashboard_count': 12,
            'type': 'manual_dashboard_list',
            'id': 295
        }
    ]
}
[
    "200",
    {
        "dashboard_lists" => [
            {
                "is_favorite" => true,
                "name" => "My Dashboard List B",
                "dashboard_count" => 22,
                "author" => {
                    "handle" => "test1@datadoghq.com",
                    "name" => "Author Name"
                },
                "created" => "2017-09-14T14:59:59.040891+00:00",
                "type" => "manual_dashboard_list",
                "dashboards" => nil,
                "modified" => "2018-03-16T13:03:52.698416+00:00",
                "id" => 142
            },
            {
                "is_favorite" => false,
                "name" => "My Dashboard List A",
                "dashboard_count" => 12,
                "author" => {
                    "handle" => "test2@datadoghq.com",
                    "name" => "Other Author Name"
                },
                "created" => "2017-11-17T11:17:43.273931+00:00",
                "type" => "manual_dashboard_list",
                "dashboards" => nil,
                "modified" => "2018-03-16T13:03:43.835281+00:00",
                "id" => 295
            }
        ]
    }
]
{
    "dashboard_lists": [
        {
            "name": "My Dashboard List B",
            "created": "2017-09-14T14:59:59.040891+00:00",
            "author": {
                "handle": "test1@datadoghq.com",
                "name": "Author Name"
            },
            "dashboards": None,
            "modified": "2018-03-16T13:03:52.698416+00:00",
            "is_favorite": True,
            "dashboard_count": 22,
            "type": "manual_dashboard_list",
            "id": 142
        },
        {
            "name": "My Dashboard List A",
            "created": "2017-11-17T11:17:43.273931+00:00",
            "author": {
                "handle": "test2@datadoghq.com",
                "name": "Other Author Name"
            },
            "dashboards": None,
            "modified": "2018-03-16T13:03:43.835281+00:00",
            "is_favorite": False,
            "dashboard_count": 12,
            "type": "manual_dashboard_list",
            "id": 295
        }
    ]
}

Create a Dashboard List

Create an empty dashboard list.

Arguments
  • name [required]: The name of the dashboard list.
Signature

POST /v1/dashboard/lists/manual

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

name = 'My Dashboard List'

api.DashboardList.create(name=name)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

name = 'My Dashboard List'

result = dog.create_dashboard_list(name)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
        "name": "My Dashboard List"
}' \
"https://api.datadoghq.com/api/v1/dashboard/lists/manual?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'name': 'My Dashboard List',
    'created': '2018-03-16T09:44:41.476018+00:00',
    'author': {
        'handle': 'test1@datadoghq.com',
        'name': 'Author Name'
    },
    'dashboards': None,
    'modified': '2018-03-16T09:44:41.476030+00:00',
    'is_favorite': False,
    'dashboard_count': 0,
    'type': 'manual_dashboard_list',
    'id': 4741
}
[
    "200",
    {
        "is_favorite" => false,
        "name" => "My Dashboard List",
        "dashboard_count" => 0,
        "author" => {
            "handle" => "test1@datadoghq.com",
            "name" => "Author Name"
        },
        "created" => "2018-03-16T09:51:47.905261+00:00",
        "type" => "manual_dashboard_list",
        "dashboards" => nil,
        "modified" => "2018-03-16T09:51:47.905273+00:00",
        "id" => 4741
    }
]
{
    "name": "My Dashboard List",
    "created": "2018-03-16T09:44:41.476018+00:00",
    "author": {
        "handle": "test1@datadoghq.com",
        "name": "Author Name"
    },
    "dashboards": None,
    "modified": "2018-03-16T09:44:41.476030+00:00",
    "is_favorite": False,
    "dashboard_count": 0,
    "type": "manual_dashboard_list",
    "id": 4741
}

Update a Dashboard List

Update the name of a dashboard list

Arguments
  • name [required]: The name of the dashboard list.
Signature

PUT /v1/dashboard/lists/manual/<LIST_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

list_id = 4741
name = 'My Updated Dashboard List'

api.DashboardList.update(list_id, name=name)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

list_id = 4741
name = 'My Updated Dashboard List'

result = dog.update_dashboard_list(list_id, name)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X PUT -H "Content-type: application/json" \
-d '{
        "name": "My Updated Dashboard List"
}' \
"https://api.datadoghq.com/api/v1/dashboard/lists/manual/${list_id}?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    'name': 'My Updated Dashboard List',
    'created': '2018-03-16T09:44:41.476018+00:00',
    'author': {
        'handle': 'test1@datadoghq.com',
        'name': 'Author Name'
    },
    'dashboards': None,
    'modified': '2018-03-16T13:45:42.288026+00:00',
    'is_favorite': False,
    'dashboard_count': 5,
    'type': 'manual_dashboard_list',
    'id': 4741
}
[
    "200",
    {
        "is_favorite" => false,
        "name" => "My Updated Dashboard List",
        "dashboard_count" => 5,
        "author" => {
            "handle" => "test1@datadoghq.com",
            "name" => "Author Name"
        },
        "created" => "2018-03-16T09:44:41.476018+00:00",
        "type" => "manual_dashboard_list",
        "dashboards" => nil,
        "modified" => "2018-03-16T13:45:42.288026+00:00",
        "id" => 4741
    }
]
{
    "name": "My Updated Dashboard List",
    "created": "2018-03-16T09:44:41.476018+00:00",
    "author": {
        "handle": "test1@datadoghq.com",
        "name": "Author Name"
    },
    "dashboards": None,
    "modified": "2018-03-16T13:45:42.288026+00:00",
    "is_favorite": False,
    "dashboard_count": 5,
    "type": "manual_dashboard_list",
    "id": 4741
}

Delete a Dashboard List

Delete an existing dashboard list.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

DELETE /v1/dashboard/lists/manual/<LIST_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.DashboardList.delete(4741)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

result = dog.delete_dashboard_list(4741)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X DELETE \
"https://api.datadoghq.com/api/v1/dashboard/lists/manual/${list_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'deleted_dashboard_list_id': 4741
}
[
    "200",
    {
        "deleted_dashboard_list_id" => 4741
    }
]
{
    "deleted_dashboard_list_id": 4741
}

Get Items of a Dashboard List

Fetch the dashboard list’s dashboard definitions.

This endpoint has been updated to reflect the new Dashboard API changes. Documentation for old endpoint is available here:
ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v2/dashboard/lists/manual/<LIST_ID>/dashboards

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.DashboardList.v2.get_items(4741)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

result = dog.v2.get_items_of_dashboard_list(4741)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X GET \
"https://api.datadoghq.com/api/v2/dashboard/lists/manual/${list_id}/dashboards?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'total': 5,
    'dashboards': [
        {
            'popularity': 0,
            'is_shared': False,
            'author': {
                'handle': None,
                'name': None
            },
            'url': '/screen/integration/87/aws-dynamodb',
            'title': 'AWS DynamoDB',
            'modified': None,
            'created': None,
            'is_favorite': True,
            'is_read_only': True,
            'type': 'integration_screenboard',
            'id': '87',
            'icon': '/static/v/34.254868/images/saas_logos/small/amazon_dynamodb.png'
        },
        {
            'popularity': 0,
            'is_shared': False,
            'author': {
                'handle': None,
                'name': None
            },
            'url': '/dash/integration/23/postgres---metrics',
            'title': 'Postgres - Metrics',
            'modified': None,
            'created': None,
            'is_favorite': True,
            'is_read_only': True,
            'type': 'integration_timeboard',
            'id': '23',
            'icon': '/static/v/34.254868/images/saas_logos/small/postgres.png'
        },
        {
            'popularity': 0,
            'is_shared': False,
            'author': {
                'handle': 'test1@datadoghq.com',
                'name': 'Author Name'
            },
            'url': '/dash/qts-q2k-yq6/trace-api',
            'title': 'Trace API',
            'modified': '2018-03-16T13:39:39.517133+00:00',
            'created': '2015-10-21T13:22:48.633391+00:00',
            'is_favorite': False,
            'is_read_only': False,
            'type': 'custom_timeboard',
            'id': 'qts-q2k-yq6',
            'icon': None
        },
        {
            'popularity': 0,
            'is_shared': False,
            'author': {
                'handle': 'test2@datadoghq.com',
                'name': 'Other Author Name'
            },
            'url': '/screen/rys-xwq-geh/agent-stats',
            'title': 'Agent Stats',
            'modified': '2018-03-16T12:54:25.968134+00:00',
            'created': '2014-06-18T18:19:00.974763+00:00',
            'is_favorite': False,
            'is_read_only': False,
            'type': 'custom_screenboard',
            'id': 'rys-xwq-geh',
            'icon': None
        },
        {
            'popularity': 0,
            'is_shared': False,
            'author': {
                'handle': None,
                'name': None
            },
            'url': '/dash/host/3245468',
            'title': 'agent-gui',
            'modified': None,
            'created': None,
            'is_favorite': False,
            'is_read_only': True,
            'type': 'host_timeboard',
            'id': '3245468',
            'icon': None
        }
    ]
}
[
    "200",
    {
        "total" => 5,
        "dashboards" => [
            {
                "popularity" => 0,
                "title" => "AWS DynamoDB",
                "is_favorite" => true,
                "id" => "87",
                "icon" => "/static/v/34.254868/images/saas_logos/small/amazon_dynamodb.png",
                "is_shared" => false,
                "author" => {
                    "handle" => nil,
                    "name" => nil
                },
                "url" => "/screen/integration/87/aws-dynamodb",
                "created" => nil,
                "modified" => nil,
                "is_read_only" => true,
                "type" => "integration_screenboard"
            },
            {
                "popularity" => 0,
                "title" => "Postgres - Metrics",
                "is_favorite" => true,
                "id" => "23",
                "icon" => "/static/v/34.254868/images/saas_logos/small/postgres.png",
                "is_shared" => false,
                "author" => {
                    "handle" => nil,
                    "name" => nil
                },
                "url" => "/dash/integration/23/postgres---metrics",
                "created" => nil,
                "modified" => nil,
                "is_read_only" => true,
                "type" => "integration_timeboard"
            },
            {
                "popularity" => 0,
                "title" => "Trace API",
                "is_favorite" => false,
                "id" => "qts-q2k-yq6",
                "icon" => nil,
                "is_shared" => false,
                "author" => {
                    "handle" => "test1@datadoghq.com",
                    "name" => "Author Name"
                },
                "url" => "/dash/qts-q2k-yq6/trace-api",
                "created" => "2015-10-21T13:22:48.633391+00:00",
                "modified" => "2018-03-16T13:39:39.517133+00:00",
                "is_read_only" => false,
                "type" => "custom_timeboard"
            },
            {
                "popularity" => 0,
                "title" => "Agent Stats",
                "is_favorite" => false,
                "id" => "rys-xwq-geh",
                "icon" => nil,
                "is_shared" => false,
                "author" => {
                    "handle" => "test2@datadoghq.com",
                    "name" => "Other Author Name"
                },
                "url" => "/screen/rys-xwq-geh/agent-stats",
                "created" => "2014-06-18T18:19:00.974763+00:00",
                "modified" => "2018-03-16T12:54:25.968134+00:00",
                "is_read_only" => false,
                "type" => "custom_screenboard"
            },
            {
                "popularity" => 0,
                "title" => "agent-gui",
                "is_favorite" => false,
                "id" => "3245468",
                "icon" => nil,
                "is_shared" => false,
                "author" => {
                    "handle" => nil,
                    "name" => nil
                },
                "url" => "/dash/host/3245468",
                "created" => nil,
                "modified" => nil,
                "is_read_only" => true,
                "type" => "host_timeboard"
            }
        ]
    }
]
{
    "total": 5,
    "dashboards": [
        {
            "popularity": 0,
            "is_shared": False,
            "author": {
                "handle": None,
                "name": None
            },
            "url": "/screen/integration/87/aws-dynamodb",
            "title": "AWS DynamoDB",
            "modified": None,
            "created": None,
            "is_favorite": True,
            "is_read_only": True,
            "type": "integration_screenboard",
            "id": "87",
            "icon": "/static/v/34.254868/images/saas_logos/small/amazon_dynamodb.png"
        },
        {
            "popularity": 0,
            "is_shared": False,
            "author": {
                "handle": None,
                "name": None
            },
            "url": "/dash/integration/23/postgres---metrics",
            "title": "Postgres - Metrics",
            "modified": None,
            "created": None,
            "is_favorite": True,
            "is_read_only": True,
            "type": "integration_timeboard",
            "id": "23",
            "icon": "/static/v/34.254868/images/saas_logos/small/postgres.png"
        },
        {
            "popularity": 0,
            "is_shared": False,
            "author": {
                "handle": "test1@datadoghq.com",
                "name": "Author Name"
            },
            "url": "/dash/qts-q2k-yq6/trace-api",
            "title": "Trace API",
            "modified": "2018-03-16T13:39:39.517133+00:00",
            "created": "2015-10-21T13:22:48.633391+00:00",
            "is_favorite": False,
            "is_read_only": False,
            "type": "custom_timeboard",
            "id": "qts-q2k-yq6",
            "icon": None
        },
        {
            "popularity": 0,
            "is_shared": False,
            "author": {
                "handle": "test2@datadoghq.com",
                "name": "Other Author Name"
            },
            "url": "/screen/rys-xwq-geh/agent-stats",
            "title": "Agent Stats",
            "modified": "2018-03-16T12:54:25.968134+00:00",
            "created": "2014-06-18T18:19:00.974763+00:00",
            "is_favorite": False,
            "is_read_only": False,
            "type": "custom_screenboard",
            "id": "rys-xwq-geh",
            "icon": None
        },
        {
            "popularity": 0,
            "is_shared": False,
            "author": {
                "handle": None,
                "name": None
            },
            "url": "/dash/host/3245468",
            "title": "agent-gui",
            "modified": None,
            "created": None,
            "is_favorite": False,
            "is_read_only": True,
            "type": "host_timeboard",
            "id": "3245468",
            "icon": None
        }
    ]
}

Add Items to a Dashboard List

Add dashboards to an existing dashboard list.

This endpoint has been updated to reflect the new Dashboard API changes. Documentation for old endpoint is available here:
ARGUMENTS
  • dashboards [required]: A list of dashboards to add to the list. Dashboard definitions follow this form:

    • type [required]: The type of the dashboard. The type must be one of:

      • "custom_timeboard"
      • "custom_screenboard"
      • "integration_screenboard"
      • "integration_timeboard"
      • "host_timeboard"
    • id [required]: The id of the dashboard.

Signature

POST /v2/dashboard/lists/manual/<LIST_ID>/dashboards

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

list_id = 4741
dashboards = [
    {
        'type': 'custom_screenboard',
        'id': 'rys-xwq-geh'
    },
    {
        'type': 'custom_timeboard',
        'id': 'qts-q2k-yq6'
    },
    {
        'type': 'integration_screenboard',
        'id': '87'
    },
    {
        'type': 'integration_timeboard',
        'id': '23'
    },
    {
        'type': 'host_timeboard',
        'id': '3245468'
    }
]

api.DashboardList.v2.add_items(list_id, dashboards=dashboards)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

list_id = 4741
dashboards = [
    {
        "type" => "custom_screenboard",
        "id" => "rys-xwq-geh"
    },
    {
        "type" => "custom_timeboard",
        "id" => "qts-q2k-yq6"
    },
    {
        "type" => "integration_screenboard",
        "id" => "87"
    },
    {
        "type" => "integration_timeboard",
        "id" => "23"
    },
    {
        "type" => "host_timeboard",
        "id" => "3245468"
    }
]

result = dog.v2.add_items_to_dashboard_list(list_id, dashboards)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X POST -H "Content-type: application/json" \
-d '{
        "dashboards": [
            {
                "type": "custom_screenboard",
                "id": "rys-xwq-geh"
            },
            {
                "type": "custom_timeboard",
                "id": "qts-q2k-yq6"
            },
            {
                "type": "integration_screenboard",
                "id": "87"
            },
            {
                "type": "integration_timeboard",
                "id": "23"
            },
            {
                "type": "host_timeboard",
                "id": "3245468"
            }
        ]
}' \
"https://api.datadoghq.com/api/v2/dashboard/lists/manual/${list_id}/dashboards?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'added_dashboards_to_list': [
        {
            'type': 'custom_screenboard',
            'id': 'rys-xwq-geh'
        },
        {
            'type': 'custom_timeboard',
            'id': 'qts-q2k-yq6'
        },
        {
            'type': 'integration_screenboard',
            'id': '87'
        },
        {
            'type': 'integration_timeboard',
            'id': '23'
        },
        {
            'type': 'host_timeboard',
            'id': '3245468'
        }
    ]
}
[
    "200",
    {
        "added_dashboards_to_list" => [
            {
                "type" => "custom_screenboard",
                "id" => "rys-xwq-geh"
            },
            {
                "type" => "custom_timeboard",
                "id" => "qts-q2k-yq6"
            },
            {
                "type" => "integration_screenboard",
                "id" => "87"
            },
            {
                "type" => "integration_timeboard",
                "id" => "23"
            },
            {
                "type" => "host_timeboard",
                "id" => "3245468"
            }
        ]
    }
]
{
    "added_dashboards_to_list": [
        {
            "type": "custom_screenboard",
            "id": "rys-xwq-geh"
        },
        {
            "type": "custom_timeboard",
            "id": "qts-q2k-yq6"
        },
        {
            "type": "integration_screenboard",
            "id": "87"
        },
        {
            "type": "integration_timeboard",
            "id": "23"
        },
        {
            "type": "host_timeboard",
            "id": "3245468"
        }
    ]
}

Update Items of a Dashboard List

Update dashboards of an existing dashboard list.

This endpoint has been updated to reflect the new Dashboard API changes. Documentation for old endpoint is available here:
ARGUMENTS
  • dashboards [required]: The new list of dashboards for the dashboard list. Dashboard definitions follow this form:

    • type [required]: The type of the dashboard. The type must be one of:

      • "custom_timeboard"
      • "custom_screenboard"
      • "integration_screenboard"
      • "integration_timeboard"
      • "host_timeboard"
    • id [required]: The id of the dashboard.

Signature

PUT /v2/dashboard/lists/manual/<LIST_ID>/dashboards

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

list_id = 4741
dashboards = [
    {
        'type': 'custom_screenboard',
        'id': 'rys-xwq-geh'
    },
    {
        'type': 'custom_timeboard',
        'id': 'qts-q2k-yq6'
    },
    {
        'type': 'integration_screenboard',
        'id': '87'
    },
    {
        'type': 'integration_timeboard',
        'id': '23'
    },
    {
        'type': 'host_timeboard',
        'id': '3245468'
    }
]

api.DashboardList.v2.update_items(list_id, dashboards=dashboards)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

list_id = 4741
dashboards = [
    {
        "type" => "custom_screenboard",
        "id" => "rys-xwq-geh"
    },
    {
        "type" => "custom_timeboard",
        "id" => "qts-q2k-yq6"
    },
    {
        "type" => "integration_screenboard",
        "id" => "87"
    },
    {
        "type" => "integration_timeboard",
        "id" => "23"
    },
    {
        "type" => "host_timeboard",
        "id" => "3245468"
    }
]

result = dog.v2.update_items_of_dashboard_list(list_id, dashboards)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X PUT -H "Content-type: application/json" \
-d '{
        "dashboards": [
            {
                "type": "custom_screenboard",
                "id": "rys-xwq-geh"
            },
            {
                "type": "custom_timeboard",
                "id": "qts-q2k-yq6"
            },
            {
                "type": "integration_screenboard",
                "id": "87"
            },
            {
                "type": "integration_timeboard",
                "id": "23"
            },
            {
                "type": "host_timeboard",
                "id": "3245468"
            }
        ]
}' \
"https://api.datadoghq.com/api/v2/dashboard/lists/manual/${list_id}/dashboards?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'dashboards': [
        {
            'type': 'custom_timeboard',
            'id': 'qts-q2k-yq6'
        },
        {
            'type': 'custom_screenboard',
            'id': 'rys-xwq-geh'
        },
        {
            'type': 'integration_timeboard',
            'id': '23'
        },
        {
            'type': 'integration_screenboard',
            'id': '87'
        },
        {
            'type': 'host_timeboard',
            'id': '3245468'
        }
    ]
}
[
    "200",
    {
        "dashboards" => [
            {
                "type" => "custom_timeboard",
                "id" => "qts-q2k-yq6"
            },
            {
                "type" => "custom_screenboard",
                "id" => "rys-xwq-geh"
            },
            {
                "type" => "integration_timeboard",
                "id" => "23"
            },
            {
                "type" => "integration_screenboard",
                "id" => "87"
            },
            {
                "type" => "host_timeboard",
                "id" => "3245468"
            }
        ]
    }
]
{
    "dashboards": [
        {
            "type": "custom_timeboard",
            "id": "qts-q2k-yq6"
        },
        {
            "type": "custom_screenboard",
            "id": "rys-xwq-geh"
        },
        {
            "type": "integration_timeboard",
            "id": "23"
        },
        {
            "type": "integration_screenboard",
            "id": "87"
        },
        {
            "type": "host_timeboard",
            "id": "3245468"
        }
    ]
}

Delete Items from a Dashboard List

Delete dashboards from an existing dashboard list.

This endpoint has been updated to reflect the new Dashboard API changes. Documentation for old endpoint is available here:
ARGUMENTS
  • dashboards [required]: A list of dashboards to remove from the list. Dashboard definitions follow this form:

    • type [required]: The type of the dashboard. The type must be one of:

      • "custom_timeboard"
      • "custom_screenboard"
      • "integration_screenboard"
      • "integration_timeboard"
      • "host_timeboard"
    • id [required]: The id of the dashboard.

Signature

DELETE /v2/dashboard/lists/manual/<LIST_ID>/dashboards

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

list_id = 4741
dashboards = [
    {
        'type': 'custom_screenboard',
        'id': 'rys-xwq-geh'
    },
    {
        'type': 'custom_timeboard',
        'id': 'qts-q2k-yq6'
    },
    {
        'type': 'integration_screenboard',
        'id': '87'
    },
    {
        'type': 'integration_timeboard',
        'id': '23'
    },
    {
        'type': 'host_timeboard',
        'id': '3245468'
    }
]

api.DashboardList.v2.delete_items(list_id, dashboards=dashboards)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

list_id = 4741
dashboards = [
    {
        "type" => "custom_screenboard",
        "id" => "rys-xwq-geh"
    },
    {
        "type" => "custom_timeboard",
        "id" => "qts-q2k-yq6"
    },
    {
        "type" => "integration_screenboard",
        "id" => "87"
    },
    {
        "type" => "integration_timeboard",
        "id" => "23"
    },
    {
        "type" => "host_timeboard",
        "id" => "3245468"
    }
]

result = dog.v2.delete_items_from_dashboard_list(list_id, dashboards)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

list_id=4741

curl -X DELETE -H "Content-type: application/json" \
-d '{
        "dashboards": [
            {
                "type": "custom_screenboard",
                "id": "rys-xwq-geh"
            },
            {
                "type": "custom_timeboard",
                "id": "qts-q2k-yq6"
            },
            {
                "type": "integration_screenboard",
                "id": "87"
            },
            {
                "type": "integration_timeboard",
                "id": "23"
            },
            {
                "type": "host_timeboard",
                "id": "3245468"
            }
        ]
}' \
"https://api.datadoghq.com/api/v2/dashboard/lists/manual/${list_id}/dashboards?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'deleted_dashboards_from_list': [
        {
            'type': 'custom_screenboard',
            'id': 'rys-xwq-geh'
        },
        {
            'type': 'custom_timeboard',
            'id': 'qts-q2k-yq6'
        },
        {
            'type': 'integration_screenboard',
            'id': '87'
        },
        {
            'type': 'integration_timeboard',
            'id': '23'
        },
        {
            'type': 'host_timeboard',
            'id': '3245468'
        }
    ]
}
[
    "200",
    {
        "deleted_dashboards_from_list" => [
            {
                "type" => "custom_screenboard",
                "id" => "rys-xwq-geh"
            },
            {
                "type" => "custom_timeboard",
                "id" => "qts-q2k-yq6"
            },
            {
                "type" => "integration_screenboard",
                "id" => "87"
            },
            {
                "type" => "integration_timeboard",
                "id" => "23"
            },
            {
                "type" => "host_timeboard",
                "id" => "3245468"
            }
        ]
    }
]
{
    "deleted_dashboards_from_list": [
        {
            "type": "custom_screenboard",
            "id": "rys-xwq-geh"
        },
        {
            "type": "custom_timeboard",
            "id": "qts-q2k-yq6"
        },
        {
            "type": "integration_screenboard",
            "id": "87"
        },
        {
            "type": "integration_timeboard",
            "id": "23"
        },
        {
            "type": "host_timeboard",
            "id": "3245468"
        }
    ]
}

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(s) to which the downtime applies, e.g. host:app2. Provide multiple scopes as a comma-separated list, e.g. env:dev,env:prod. The resulting downtime applies to sources that matches ALL provided scopes (i.e. env:dev AND env:prod), NOT any of them.
  • monitor_tags [optional, default=no monitor tag filter]: A comma-separated list of monitor tags, i.e. tags that are applied directly to monitors, not tags that are used in monitor queries (which are filtered by the scope parameter), to which the downtime applies. The resulting downtime applies to monitors that match ALL provided monitor tags (i.e. service:postgres AND team:frontend), NOT any of them.
  • monitor_id [optional, default=None]: A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.
  • start [optional, default=None]: POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.
  • end [optional, default=None]: POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely (i.e. until you cancel it).
  • 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
  • timezone [optional, default = UTC]: The timezone for the downtime.
  • recurrence [optional, default=None]: An object defining the recurrence of the downtime with a variety of parameters:
    • type the type of recurrence. Choose from: days, weeks, months, years.
    • period how often to repeat as an integer. For example to repeat every 3 days, select a type of days and a period of 3.
    • week_days (optional) a list of week days to repeat on. Choose from: Mon, Tue, Wed, Thu, Fri, Sat or Sun. Only applicable when type is weeks. First letter must be capitalized.
    • until_occurrences (optional) how many times the downtime is rescheduled. until_occurences and until_date are mutually exclusive
    • until_date (optional) the date at which the recurrence should end as a POSIX timestmap. until_occurences and until_date are mutually exclusive
Signature

POST /v1/downtime

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Repeat for 3 hours (starting now) on every week day for 4 weeks.
start_ts = int(time.time())
end_ts = start_ts + (3 * 60 * 60)
end_reccurrence_ts = start_ts + (4 * 7 * 24 * 60 * 60)  # 4 weeks from now

recurrence = {
    'type': 'weeks',
    'period': 1,
    'week_days': ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    'until_date': end_reccurrence_ts
}

# Schedule downtime
api.Downtime.create(
    scope='env:staging',
    start=start_ts,
    end=end_ts,
    recurrence=recurrence
)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Repeat for 3 hours(starting now) on every week day for 4 weeks.
start_ts = Time.now.to_i
end_ts = start_ts + (3 * 60 * 60)
end_reccurrence_ts = start_ts + (4 * 7 * 24 * 60 * 60)# 4 weeks from now

recurrence = {
    'type' => 'weeks',
    'period' => 1,
    'week_days' => ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    'until_date' => end_reccurrence_ts
}

# Schedule downtime
dog.schedule_downtime('env:testing', :start => start_ts, :end => end_ts, :recurrence => recurrence)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

start=$(date +%s)
end=$(date -v+3H +%s)
end_recurrence=$(date -v+21d +%s)

curl -X POST -H "Content-type: application/json" \
-d '{
      "scope": "env:prod",
      "start": '"${start}"',
      "end": '"${end}"',
      "recurrence": {
        "type": "weeks",
        "period": 1,
        "week_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
        "until_date": '"${end_recurrence}"'
      }
}' \
    "https://api.datadoghq.com/api/v1/downtime?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'active': True,
    'canceled': None,
    'creator_id': 3658,
    'disabled': False,
    'end': 1445978817,
    'id': 169267576,
    'message': None,
    'monitor_id': None,
    'monitor_tags': ['*'],
    'parent_id': None,
    'recurrence': {
        'period': 1,
        'type': 'weeks',
        'until_date': 1448387217,
        'until_occurrences': None,
        'week_days': [
            'Mon',
            'Tue',
            'Wed',
            'Thu',
            'Fri'
        ]
    },
    'scope': ['env:staging'],
    'start': 1445968017,
    'updater_id': None
}
[
    "200", {
        "disabled" => false,
        "canceled" => nil,
        "active" => true,
        "message" => nil,
        "id" => 169267581,
        "end" => 1445978819,
        "parent_id" => nil,
        "monitor_id" => nil,
        "monitor_tags": ["*"],
        "recurrence" => {
            "until_date" => 1448387219,
            "until_occurrences" => nil,
            "week_days" => ["Mon", "Tue", "Wed", "Thu", "Fri"],
            "type" => "weeks",
            "period" => 1
        },
        "start" => 1445968019,
        "creator_id" => 3658,
        "scope" => ["env:testing"],
        "updater_id" => nil
    }
]
{
  "active": true,
  "canceled": null,
  "creator_id": 3658,
  "disabled": false,
  "end": 1445979093,
  "id": 169267786,
  "message": null,
  "monitor_id": null,
  "monitor_tags": ["*"],
  "parent_id": null,
  "recurrence": {
    "period": 1,
    "type": "weeks",
    "until_date": 1447786293,
    "until_occurrences": null,
    "week_days": [
      "Mon",
      "Tue",
      "Wed",
      "Thu",
      "Fri"
    ]
  },
  "scope": [
    "env:prod"
  ],
  "start": 1445968293,
  "updater_id": null
}

Update monitor downtime

ARGUMENTS
  • id [required]: The integer id of the downtime to be updated
  • scope [required]: The scope to which the downtime applies, e.g. ‘host:app2’. Provide multiple scopes as a comma-separated list, e.g. ‘env:dev,env:prod’. The resulting downtime applies to sources that matches ALL provided scopes (i.e. env:dev AND env:prod), NOT any of them.
  • monitor_tags [optional, default=no monitor tag filter]: A comma-separated list of monitor tags, i.e. tags that are applied directly to monitors, not tags that are used in monitor queries (which are filtered by the scope parameter), to which the downtime applies. The resulting downtime applies to monitors that match ALL provided monitor tags (i.e. service:postgres AND team:frontend), NOT any of them.
  • monitor_id [optional, default=None]: A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.
  • start [optional, default = original start]: POSIX timestamp to start the downtime.
  • end [optional, default = original end]: POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely (i.e. until you cancel it).
  • message [required, 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
  • timezone [optional, default = original timezone ]: The timezone for the downtime.
  • recurrence [optional, default = original recurrence]: An object defining the recurrence of the downtime with a variety of parameters:
    • type the type of recurrence. Choose from: days, weeks, months, years.
    • period how often to repeat as an integer. For example to repeat every 3 days, select a type of days and a period of 3.
    • week_days (optional) a list of week days to repeat on. Choose from: Mon, Tue, Wed, Thu, Fri, Sat or Sun. Only applicable when type is weeks. First letter must be capitalized.
    • until_occurrences (optional) how many times the downtime is rescheduled. until_occurences and until_date are mutually exclusive
    • until_date (optional) the date at which the recurrence should end as a POSIX timestmap. until_occurences and until_date are mutually exclusive
Signature

PUT /v1/downtime/<DOWNTIME_ID>

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Get an existing downtime
stagingDowntimes = []
downtimes = api.Downtime.get_all()

for item in downtimes:
    if item['scope'] == ['env:staging']:
        stagingDowntimes.append(item)

# Update that downtime
api.Downtime.update(
    stagingDowntimes[0]['id'],
    scope='env:staging',
    end=int(time.time()) + 60000,
    message="Doing some testing on staging."
)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Update downtime
stagingDowntimes = []
downtimes = dog.get_all_downtimes()
downtimes[1].each do |item |
        print item['scope']
if item['scope'] == ['env:staging']
stagingDowntimes.push item
end

end

dog.update_downtime(stagingDowntimes[0]['id'], :scope => 'env:testing', :end => Time.now.to_i + 60000, :message => "Doing some testing on staging.")
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
downtime_id=4336

# Create a downtime to update
currenttime=$(date +%s)
downtime_id=$(curl -X POST -H "Content-type: application/json" \
-d "{
      \"scope\": \"env:prod\",
      \"start\": \"${currenttime}\"
  }" \
    "https://api.datadoghq.com/api/v1/downtime?api_key=${api_key}&application_key=${app_key}" | jq '.id')

curl -X PUT -H "Content-type: application/json" \
-d '{
      "scope": "env:staging",
      "message": "Doing some testing on staging"
}' \
    "https://api.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.',
    'monitor_tags': ['*'],
    'scope': ['env:staging'],
    'start': 1420387032
}
[
    "200", {
        "end" => 1418303372,
        "disabled" => false,
        "start" => 1418224729,
        "active" => true,
        "monitor_tags": ["*"],
        "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",
  "monitor_tags": ["*"],
  "scope": [
    "env:staging"
  ],
  "start": 1418224729
}

Cancel Monitor Downtime

ARGUMENTS
  • id [required]:
    The integer id of the downtime to be canceled
Signature

DELETE /v1/downtime/<DOWNTIME_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Cancel downtime
api.Downtime.delete(1654)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Cancel downtime
dog.cancel_downtime(1655)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
downtime_id=1656

# Create a downtime to delete
currenttime=$(date +%s)
downtime_id=$(curl -X POST -H "Content-type: application/json" \
-d "{
      \"scope\": \"env:prod\",
      \"start\": \"${currenttime}\"
  }" \
    "https://api.datadoghq.com/api/v1/downtime?api_key=${api_key}&application_key=${app_key}" | jq '.id')

curl -X DELETE -H "Content-type: application/json" "https://api.datadoghq.com/api/v1/downtime/${downtime_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

This endpoint does not return JSON on successful requests.

Cancel Monitor Downtimes By Scope

This endpoint is not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

ARGUMENTS
  • scope [required]:
    Cancel all downtimes with the given scope(s), e.g.:

    • env:prod
    • role:db,role:db-slave
Signature

POST /v1/downtime/cancel/by_scope

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
#!/bin/bash

api_key="<YOUR_API_KEY>"
app_key="<YOUR_APP_KEY>"

curl -X POST -H "Content-type: application/json" -H "Accept: application/json" \
-d "{
      \"scope\": \"host:i-123\"
}" \
   "https://api.datadoghq.com/api/v1/downtime/cancel/by_scope?api_key=${api_key}&application_key=${app_key}"
Example Response
#
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
#
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
{
  "cancelled_ids":[123456789,123456790]
}

Get a monitor downtime

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/downtime/<DOWNTIME_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Get a downtime
api.Downtime.get(2910)
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

downtime_id=2473

curl "https://api.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.',
 'monitor_tags': ['*'],
 'scope': ['env:staging'],
 'start': 1420387032
 }
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
{
  "active": True,
  "disabled": False,
  "end": 1420447087,
  "id": 2910,
  "message": "Doing some testing on staging.",
  "monitor_tags": ["*"],
  "scope": ["env:staging"],
  "start": 1420387032
}

Get all monitor downtimes

ARGUMENTS
  • current_only [optional, default = False]:
    Only return downtimes that are activewhen the request is made.
Signature

GET /v1/downtime

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Get all downtimes
print api.Downtime.get_all()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Get all downtimes
print(dog.get_all_downtimes())
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -G "https://api.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,
        'monitor_tags': ['*'],
        'scope': ['env:staging'],
        'start': 1412792983
    },
    {
        'active': False,
        'disabled': True,
        'end': None,
        'id': 1626,
        'monitor_tags': ['*'],
        'scope': ['*'],
        'start': 1412792985
    }
]
[
    "200", [{
        "end" => 1412793983,
        "disabled" => true,
        "start" => 1412792983,
        "active" => false,
        "monitor_tags" => ["*"],
        "scope" => ["env:staging"],
        "id" => 1625
    }, {
        "end" => nil,
        "disabled" => true,
        "start" => 1412792985,
        "active" => false,
        "monitor_tags" => ["*"],
        "scope" => ["*"],
        "id" => 1626
    }]
]
[
  {
    "active": false,
    "disabled": true,
    "end": 1412793983,
    "id": 1625,
    "monitor_tags": ["*"],
    "scope": [
      "env:staging"
    ],
    "start": 1412792983
  },
  {
    "active": false,
    "disabled": true,
    "end": null,
    "id": 1626,
    "monitor_tags": ["*"],
    "scope": [
      "*"
    ],
    "start": 1412792985
  }
]

Embeddable graphs

Interact with embeddable graphs through the API.

Get all embeds

Gets a list of previously created embeddable graphs.

Returns: A JSON list containing information on previously created embeds from both the UI and the API. Each JSON graph response is in the same format as returned by GET api/v1/graph/embed/.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/graph/embed

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Call Embed API function
api.Embed.get_all()
require 'rubygems'
require 'dogapi'

# Initialize API Client
api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Get all with API Call
dog.get_all_embeds()
api_key="<YOUR_API_KEY>"
app_key="<YOUR_APP_KEY>"

curl -X GET "https://api.datadoghq.com/api/v1/graph/embed?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    "embedded_graphs": [
        {
            "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
            "template_variables": [],
            "html": '&lt;iframe src=&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true&quot; width=&quot;600&quot; height=&quot;300&quot; frameBorder=&quot;0&quot;&gt;&lt;/iframe&gt;',
            "graph_title": "Embed created through API",
            "revoked": False,
            "dash_url": None,
            "shared_by": 3658,
            "dash_name": None
        }
    ]
}
{
    "embedded_graphs" => [{
        "embed_id" => "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
        "template_variables" => [],
        "html" => '&lt;iframe src=&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true&quot; width=&quot;600&quot; height=&quot;300&quot; frameBorder=&quot;0&quot;&gt;&lt;/iframe&gt;',
        "graph_title" => "Embed created through API",
        "revoked" => false,
        "dash_url" => nil,
        "shared_by" => 3658,
        "dash_name" => nil
    }]
}
{ "embedded_graphs": [
    {
      "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
      "template_variables": [],
      "html": "&lt;iframe src=\&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true\&quot; width=\&quot;600\&quot; height=\&quot;300\&quot; frameBorder=\&quot;0\&quot;&gt;&lt;/iframe&gt;",
      "graph_title": "Embed created through API",
      "revoked": false,
      "dash_url": null,
      "shared_by": 3658,
      "dash_name": null
    }
  ]
}

Create embed

Creates a new embeddable graph.

Returns: A JSON consisting of the same elements returned by GET api/v1/graph/embed/. On failure, the return value is a JSON containing an error message {errors: [messages]}.

Note: If an embed already exists for the exact same query in a given organization, the older embed is returned instead of creating a new embed.

If you are interested in using template variables, see Embeddable Graphs with Template Variables.

ARGUMENTS
  • graph_json [required]:
    The graph definition in JSON. Same format that is available on the JSON tab of the graph editor
  • timeframe [optional, default=1_hour]:
    The timegrame for the graph. Must be one of:
    • 1_hour,
    • 4_hours,
    • 1_day,
    • 2_days,
    • 1_week.
  • size [optional, default=medium]:
    The size of the graph. Must be one:
    • small,
    • medium,
    • large,
    • xlarge.
  • legend [optional, default=no]:
    The flag determining if the graph includes a legend. Must be one of yes or no.
  • title [optional, default=Embed created through API]:
    Determines graph title.
    Must be at least 1 character.
Signature

POST /v1/graph/embed

Example Request
from datadog import initialize, api
import json

# Intialize request parameters including API/APP key
options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Create an embed graph definition as a dict and format as JSON
graph_json = {
    "requests": [{
        "q": "avg:system.load.1{*}"
    }],
    "viz": "timeseries",
    "events": []
}
graph_json = json.dumps(graph_json)

api.Embed.create(
    graph_json=graph_json,
    timeframe="1_hour",
    size="medium",
    legend="no"
)
require 'rubygems'
require 'dogapi'

# Initialize API Client
api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Prepare parameters
graph_json = '{
"requests": [{
    "q": "avg:system.load.1{*}"
}],
"viz": "timeseries",
"events": []
}
'
timeframe = "1_hour"
size = "medium"
legend = "no"
title = "Embed created through API"

# Create parameter hash
description = {:timeframe => timeframe, :size => size, :legend => legend, :title => title
}

# Make API Call
status, result = dog.create_embed(graph_json, description)
api_key="<YOUR_API_KEY>"
app_key="<YOUR_APP_KEY>"

curl -POST \
    -d 'graph_json={"requests":[{"q":"avg:system.load.1{*}"}],"viz":"timeseries","events":[]}' \
    -d "timeframe=1_hour" \
    -d "size=medium" \
    -d "legend=yes" \
    "https://api.datadoghq.com/api/v1/graph/embed?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables": [],
    "html": '&lt;iframe src=&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true&quot; width=&quot;600&quot; height=&quot;300&quot; frameBorder=&quot;0&quot;&gt;&lt;/iframe&gt;',
    "graph_title": "Embed created through API",
    "revoked": False,
    "dash_url": None,
    "shared_by": 3658,
    "dash_name": None
}
{
    "embed_id" => "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables" => [],
    "html" => '&lt;iframe src=&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true&quot; width=&quot;600&quot; height=&quot;300&quot; frameBorder=&quot;0&quot;&gt;&lt;/iframe&gt;',
    "graph_title" => "Embed created through API",
    "revoked" => false,
    "dash_url" => nil,
    "shared_by" => 3658,
    "dash_name" => nil
}
{
  "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
  "template_variables": [],
  "html": "&lt;iframe src=\&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true\&quot; width=\&quot;600\&quot; height=\&quot;300\&quot; frameBorder=\&quot;0\&quot;&gt;&lt;/iframe&gt;",
  "graph_title": "Embed created through API",
  "revoked": false,
  "dash_url": null,
  "shared_by": 3658,
  "dash_name": null
}

Get specific embed

Get the HTML fragment for a previously generated embed with embed_id.

Returns: A JSON object with 8 elements:

  • embed_id: Token of the embed
  • graph_title: Tile of the graph
  • dash_name: Name of the dashboard the graph is on (null if none)
  • dash_url: URL of the dashboard the graph is on (null if none)
  • shared_by: ID of the use who shared the embed
  • html: HTML fragment for the embed (iframe)
  • revoked: Boolean flag for whther or not the embed is revoked

On failure, the return value is a JSON containing an error message {errors: [messages]}.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/graph/embed/<EMBED_ID>

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Set Embed ID (token)
embed_id = "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

# Call Embed API function
api.Embed.get(embed_id, legend="no", size="medium", timeframe="1_hour")
require 'rubygems'
require 'dogapi'

# Initialize API Client
api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Initialize Embed Token / ID
embed_id = "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

# Get embed with API Call
dog.enable_embed(embed_id)
api_key="<YOUR_API_KEY>"
app_key="<YOUR_APP_KEY>"

embed_id="5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

curl -X GET "https://api.datadoghq.com/api/v1/graph/embed/${embed_id}?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables": [],
    "html": '&lt;iframe src=&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true&quot; width=&quot;600&quot; height=&quot;300&quot; frameBorder=&quot;0&quot;&gt;&lt;/iframe&gt;',
    "graph_title": "Embed created through API",
    "revoked": False,
    "dash_url": None,
    "shared_by": 3658,
    "dash_name": None
}
{
    "embed_id" => "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables" => [],
    "html" => '&lt;iframe src=&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true&quot; width=&quot;600&quot; height=&quot;300&quot; frameBorder=&quot;0&quot;&gt;&lt;/iframe&gt;',
    "graph_title" => "Embed created through API",
    "revoked" => false,
    "dash_url" => nil,
    "shared_by" => 3658,
    "dash_name" => nil
}
{
  "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
  "template_variables": [],
  "html": "&lt;iframe src=\&quot;https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&amp;height=300&amp;width=600&amp;legend=true\&quot; width=\&quot;600\&quot; height=\&quot;300\&quot; frameBorder=\&quot;0\&quot;&gt;&lt;/iframe&gt;",
  "graph_title": "Embed created through API",
  "revoked": false,
  "dash_url": null,
  "shared_by": 3658,
  "dash_name": null
}

Enable embed

Enable a specified embed.

Returns: A JSON containing the success message {success: [message]}. On failure, the return value is a JSON containing an error message {errors: [messages]}.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/graph/embed/<EMBED_ID>/enable

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Set Embed ID (token)
embed_id = "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

# Call Embed API function
api.Embed.enable(embed_id)
require 'rubygems'
require 'dogapi'

# Initialize API Client
api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Initialize Embed Token / ID
embed_id = "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

# Enable with API Call
dog.enable_embed(embed_id)
api_key="<YOUR_API_KEY>"
app_key="<YOUR_APP_KEY>"
embed_id="5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

curl -X GET "https://api.datadoghq.com/api/v1/graph/embed/${embed_id}/enable?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    "success": "Embed 5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c successfully enabled."
}
{
    "success" => "Embed 5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c successfully enabled."
}
{
  "success": "Embed 5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c successfully enabled."
}

Revoke embed

Revoke a specified embed.

Returns: A JSON containing the success message {success: [message]}. On failure, the return value is a JSON containing an error message {errors: [messages]}.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/graph/embed/<EMBED_ID>/revoke

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Set Embed ID (token)
embed_id = "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

# Call Embed API function
api.Embed.revoke(embed_id)
require 'rubygems'
require 'dogapi'

# Initialize API Client
api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Initialize Embed Token / ID
embed_id = "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

# Revoke with API Call
dog.revoke_embed(embed_id)
api_key="<YOUR_API_KEY>"
app_key="<YOUR_APP_KEY>"

embed_id="5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"

curl -X GET "https://api.datadoghq.com/api/v1/graph/embed/${embed_id}/revoke?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    "success": "Embed 5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c successfully revoked."
}
{
    "success" => "Embed 5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c successfully revoked."
}
{
  "success": "Embed 5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c successfully revoked."
}

Events

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

Events are limited to 4000 characters. If an event is sent out with a message containing more than 4000 characters only the 4000 first characters are displayed.

Post an event

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

ARGUMENTS
  • title [required]: The event title. Limited to 100 characters. Use msg_title with the Datadog Ruby library.
  • text [required]: The body of the event. Limited to 4000 characters. The text supports markdown. Use msg_text with the Datadog Ruby library
  • date_happened [optional, default = now]: POSIX timestamp of the event. Must be sent as an integer (i.e. no quotes). Limited to events no older than 1 year, 24 days (389 days)
  • priority [optional, default = normal]: The priority of the event: normal or low.
  • host [optional, default=None]: Host name to associate with the event. Any tags associated with the host are also applied to this event.
  • tags [optional, default=None]: A list of tags to apply to the event.
  • alert_type [optional, default = info]: If it’s an alert event, set its type between: error, warning, info, and success.
  • aggregation_key [optional, default=None]: An arbitrary string to use for aggregation. Limited to 100 characters. If you specify a key, all events using that key are grouped together in the Event Stream.
  • source_type_name [optional, default=None]: The type of event being posted. Options: nagios, hudson, jenkins, my_apps, chef, puppet, git, bitbucketComplete list of source attribute values
  • related_event_id [optional, default=None]: ID of the parent event. Must be sent as an integer (i.e. no quotes).
  • device_name [optional, default=None]: A list of device names to post the event with.
Signature

POST /v1/events

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_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)

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

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

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

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

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


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://api.datadoghq.com/api/v1/events?api_key=<YOUR_API_KEY>"

Example Response
{
    'event':
    {
        'date_happened': 1419436860,
        'handle': None,
        'id': 2603387619536318140,
        'priority': 'normal',
        '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'
}
[
    "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
        }
    }
]
{
  "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"
}

Get an event

This endpoint allows you to query for event details. Note: if the event you’re querying contains markdown formatting of any kind, you may see characters such as %,\,n in your output

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/events/<EVENT_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

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

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

event_id = '1375909614428331251'
dog.get_event(event_id)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
event_id=1377281704830403917

# Create an event to get
event_id=$(curl  -X POST -H "Content-type: application/json" -d "{\"title\": \"Did you hear the news today?\"}" "https://api.datadoghq.com/api/v1/events?api_key=<YOUR_API_KEY>" | jq -r '.event.url|ltrimstr("https://app.datadoghq.com/event/event?id=")')
sleep 5

curl "https://api.datadoghq.com/api/v1/events/${event_id}?api_key=${api_key}&application_key=${app_key}"
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'
    }
}
[
    "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" => "{}"
        }
    }
]
{
  "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"
  }
}

Query the event stream

The event stream can be queried and filtered by time, priority, sources and tags. Note: if the event you’re querying contains markdown formatting of any kind, you may see characters such as %,\,n in your output

ARGUMENTS
  • start [required]: POSIX timestamp.
  • end [required]: POSIX timestamp.
  • priority [optional, default=None]: Priority of your events: low or normal.
  • sources [optional, default=None]: A comma separated string of sources.
  • tags [optional, default=None]: A comma separated string of tags. To use a negative tag filter, prefix your tag with -. See the Event Stream documentation to learn more.
  • unaggregated [optional, default=false]: Set unaggregated to true to return all events within the specified [start,end] timeframe. Otherwise if an event is aggregated to a parent event with a timestamp outside of the timeframe, it won’t be available in the output.
Signature

GET /v1/events

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

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

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

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

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

dog.stream(start_time, end_time, :priority => "normal", :tags => ["-env:dev,application:web"], :unaggregated => true)
# Note: this endpoint only accepts form-encoded requests.
currenttime=$(date +%s)
currenttime2=$(date --date='1 day ago' +%s)

curl -G -H "Content-type: application/json" \
    -d "start=${currenttime2}" \
    -d "end=${currenttime}" \
    -d "sources=My Apps" \
    -d "tags=-env:dev,application:web" \
    -d "unaggregated=true"\
    -d "api_key=<YOUR_API_KEY>" \
    -d "application_key=<YOUR_APP_KEY>" \
    "https://api.datadoghq.com/api/v1/events"
Example Response
{
    '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'
        }
    ]
}
["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"
        }]
    }]
}]
{
  "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"
    }
  ]
}

Graphs

Take graph snapshots using the API.

Graph snapshot

Note: When a snapshot is created, there is some delay before it is available.

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 adds event bands to the graph.
  • graph_def [optional, default=None]: A JSON document defining the graph. graph_def can be used instead of metric_query. The JSON document uses the grammar defined here and should be formatted to a single line then URLEncoded.
  • title [optional, default=None]: A title for the graph. If no title is specified, the graph doesn’t have a title.
Signature

GET /v1/graph/snapshot

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Take a graph snapshot
end = int(time.time())
start = end - (60 * 60)
api.Graph.create(
    graph_def='{\
    "viz": "timeseries", \
    "requests": [ \
      {"q": "avg:system.load.1{*}", "conditional_formats": [], "type": "line"},\
      {"q": "avg:system.load.5{*}", "type": "line"}, \
      {"q": "avg:system.load.15{*}", "type": "line"}\
      ], \
    "events": [\
      {"q": "hosts:* ", "tags_execution": "and"}\
      ]}',
    start=start,
    end=end
)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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)

currenttime=$(date +%s)
currenttime2=$(date -v -1d +%s)

curl -G -H "Content-type: application/json" \
    -d "metric_query=system.load.1{*}" \
    -d "start=${currenttime2}" \
    -d "end=${currenttime}" \
    -d "api_key=<YOUR_API_KEY>" \
    -d "application_key=<YOUR_APP_KEY>" \
    "https://api.datadoghq.com/api/v1/graph/snapshot"

Example Response
{
    'graph_def': {"viz": "timeseries", "requests": [{"q": "avg:system.load.1{*}", "conditional_formats": [], "type": "line"}, {"q": "avg:system.load.5{*}", "type": "line"}, {"q": "avg:system.load.15{*}", "type": "line"}], "events": [{"q": "hosts:* ", "tags_execution": "and"}]}',
    '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"
}

Hosts

Search hosts

This endpoint allows searching for hosts by name, alias, or tag. Hosts live within the past 3 hours are included. Results are paginated with a max of 100 results at a time.

ARGUMENTS
  • filter [optional, default=None]: Query string to filter search results.
  • sort_field [optional, default=cpu]: Sort hosts by the given field. Options: status, apps, cpu, iowait, load
  • sort_dir [optional, default=desc]: Direction of sort. Options: asc, desc
  • start [optional, default=0]: Host result to start search from.
  • count [optional, default=100]: Number of host results to return. Max 100.
  • from [optional, default=now - 2 hours]: Number of seconds since UNIX epoch from which you want to search your hosts.
Signature

GET /v1/hosts

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.Hosts.search()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dog.search_hosts()
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -G "https://api.datadoghq.com/api/v1/hosts" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"
Example Response
{
  'total_returned': 1,
  'host_list': [
    {
      'name': 'i-deadbeef',
      'up': True,
      'is_muted': False,
      "last_reported_time": 1560000000,
      'apps': [
        'agent'
      ],
      'tags_by_source': {
        'Datadog': [
          'host:i-deadbeef'
        ],
        'Amazon Web Services': [
          'account:staging'
        ]
      },
      'aws_name': 'mycoolhost-1',
      'metrics': {
        'load': 0.5,
        'iowait': 3.2,
        'cpu': 99.0
      },
      'sources': [
        'aws',
        'agent'
      ],
      'meta': {
        'nixV': [
          'Ubuntu',
          '14.04',
          'trusty'
        ]
      },
      'host_name': 'i-deadbeef',
      'id': 123456,
      'aliases': [
        'mycoolhost-1'
      ]
    }
  ],
  'total_matching': 1
}
["200", {
  "total_returned": 1,
  "host_list": [
    {
      "name": "i-deadbeef",
      "up": true,
      "is_muted": false,
      "last_reported_time": 1560000000,
      "apps": [
        "agent"
      ],
      "tags_by_source": {
        "Datadog": [
          "host:i-deadbeef"
        ],
        "Amazon Web Services": [
          "account:staging"
        ]
      },
      "aws_name": "mycoolhost-1",
      "metrics": {
        "load": 0.5,
        "iowait": 3.2,
        "cpu": 99.0
      },
      "sources": [
        "aws",
        "agent"
      ],
      "meta": {
        "nixV": [
          "Ubuntu",
          "14.04",
          "trusty"
        ]
      },
      "host_name": "i-deadbeef",
      "id": 123456,
      "aliases": [
        "mycoolhost-1"
      ]
    }
  ],
  "total_matching": 1
}]
{
  "total_returned": 1,
  "host_list": [
    {
      "name": "i-deadbeef",
      "up": true,
      "is_muted": false,
      "last_reported_time": 1560000000,
      "apps": [
        "agent"
      ],
      "tags_by_source": {
        "Datadog": [
          "host:i-deadbeef"
        ],
        "Amazon Web Services": [
          "account:staging"
        ]
      },
      "aws_name": "mycoolhost-1",
      "metrics": {
        "load": 0.5,
        "iowait": 3.2,
        "cpu": 99.0
      },
      "sources": [
        "aws",
        "agent"
      ],
      "meta": {
        "nixV": [
          "Ubuntu",
          "14.04",
          "trusty"
        ]
      },
      "host_name": "i-deadbeef",
      "id": 123456,
      "aliases": [
        "mycoolhost-1"
      ]
    }
  ],
  "total_matching": 1
}

Host totals

This endpoint returns the total number of active and up hosts in your Datadog account. Active means the host has reported in the past hour, and up means it has reported in the past two hours.

ARGUMENTS
  • from [optional, default=now - 2 hours]: Number of seconds since UNIX epoch from which you want to get the total number of active and up hosts.
Signature

GET /v1/hosts/totals

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.Hosts.totals()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dog.host_totals()
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -G "https://api.datadoghq.com/api/v1/hosts/totals" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"
Example Response
{'total_up':1750,'total_active':1759}
["200", {"total_up":1750,"total_active":1759}]
{"total_up":1750,"total_active":1759}

Mute a host

ARGUMENTS
  • end [optional, default=None]: POSIX timestamp when the host is unmuted. If omitted, the host remains muted until explicitly unmuted.
  • message [optional, default=None]: Message to associate with the muting of this host.
  • override [optional, default=False]: If true and the host is already muted, replaces existing host mute settings.
Signature

POST /v1/host/<HOSTNAME>/mute

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Find a host to mute
hosts = api.Hosts.search(q='hosts:')
# Mute a host
api.Host.mute(hosts['results']['hosts'][0])
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

hostname = "test.host"
message = "Muting this host for a test."
end_ts = Time.now.to_i + 60 * 60
dog.mute_host(hostname, :message => message, :end => end_ts)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
      "message": "Muting this host for a test!"
}' "https://api.datadoghq.com/api/v1/host/test.host/mute?api_key=${api_key}&application_key=${app_key}"

Example Response

{
    'action': 'Muted',
    'hostname': 'test.host'
}
["200", {
	"action"=>"Muted", 
	"message"=>"Muting this host for a test.", 
	"hostname"=>"test.host", 
	"end"=>1433345249
}]
{
  "action": "Muted",
  "hostname": "test.host",
  "message": "Muting this host for a test!"
}

Unmute a host

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

POST /v1/host/<HOSTNAME>/unmute

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Find a host to unmute
hosts = api.Hosts.search(q='hosts:')

# Unmute host
api.Host.unmute(hosts['results']['hosts'][0])
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

hostname = "test.host"
dog.unmute_host(hostname)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" "https://api.datadoghq.com/api/v1/host/test.host/unmute?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    'action': 'Unmuted',
    'hostname': 'test.host'
}
["200", {
    "action" => "Unmuted",
    "hostname" => "test.host"
}]
{
  "action": "Unmuted",
  "hostname": "test.host"
}

Integration AWS

The AWS endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Configure your Datadog-AWS integration directly through Datadog API. For more information, see the AWS integration page.

List all AWS integrations

List all Datadog-AWS integrations available in your Datadog organization.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/aws

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# List AWS Accounts (role-based only) in Datadog
curl -X GET "https://api.datadoghq.com/api/v1/integration/aws?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{"accounts":
    [{
        "account_id": '112233445566',
        "role_name": "SomeDatadogRole",
        "filter_tags": ["filter123"],
        "host_tags": ["account":"demo"],
        "account_specific_namespace_rules": {"opsworks":false}
    }]
}

Create an AWS integration

Create a Datadog-Amazon Web Services integration.

Note: Using the POST method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization.

ARGUMENTS
  • account_id [required]:

    Your AWS Account ID without dashes. Consult the Datadog AWS integration to learn more about your AWS account ID.

  • access_key_id [optional, default=None]:

    If your AWS account is a GovCloud or China account, enter the corresponding Access Key ID.

  • role_name [required]:

    Your Datadog role delegation name. For more information about you AWS account Role name, see the Datadog AWS integration configuration info.

  • filter_tags [optional, default=None]:

    The array of EC2 tags (in the form key:value) defines a filter that Datadog uses when collecting metrics from EC2. Wildcards, such as ? (for single characters) and * (for multiple characters) can also be used. Only hosts that match one of the defined tags will be imported into Datadog. The rest will be ignored. Host matching a given tag can also be excluded by adding ! before the tag. e.x. env:production,instance-type:c1.*,!region:us-east-1 For more information on EC2 tagging, see the AWS tagging documentation.

  • host_tags [optional, default=None]:

    Array of tags (in the form key:value) to add to all hosts and metrics reporting through this integration.

  • account_specific_namespace_rules [optional, default=None]:

    An object (in the form {"namespace1":true/false, "namespace2":true/false}) that enables or disables metric collection for specific AWS namespaces for this AWS account only. A list of namespaces can be found at the /v1/integration/aws/available_namespace_rules endpoint.

Signature

POST /v1/integration/aws

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# Create an AWS Account in Datadog
curl -X POST -H "Content-type: application/json" \
-d '{
        "account_id": "<AWS_ACCOUNT_ID>",
        "filter_tags": ["<KEY>:<VALUE>"],
        "host_tags": ["<KEY>:<VALUE>"],
        "role_name": "DatadogAWSIntegrationRole",
        "account_specific_namespace_rules": {
        	"auto_scaling": false,
        	"opsworks": false
        }
    }'\
"https://api.datadoghq.com/api/v1/integration/aws?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "external_id": "12345678910111213"
}

Update an AWS integration

Update a Datadog-Amazon Web Services integration.

Note: Using the PUT method updates your integration configuration by replacing your current configuration with the new one sent to your Datadog organization.

ARGUMENTS
  • account_id [required]:

    Your AWS Account ID without dashes. It needs to be passed as query parameter. Consult the Datadog AWS integration to learn more about your AWS account ID.

  • role_name [required]:

    Your Datadog role delegation name. It needs to be passed as query parameter. For more information about your AWS account Role name, see the Datadog AWS integration configuration info.

  • access_key_id [optional, default=None]:

    If your AWS account is a GovCloud or China account, enter the corresponding Access Key ID.

  • filter_tags [optional, default=None]:

    The array of EC2 tags (in the form key:value) defines a filter that Datadog uses when collecting metrics from EC2. Wildcards, such as ? (for single characters) and * (for multiple characters) can also be used. Only hosts that match one of the defined tags are imported into Datadog. The rest are ignored. Host matching a given tag can also be excluded by adding ! before the tag. e.x. env:production,instance-type:c1.*,!region:us-east-1 For more information on EC2 tagging, see the AWS tagging documentation.

  • host_tags [optional, default=None]:

    Array of tags (in the form key:value) to add to all hosts and metrics reporting through this integration.

  • account_specific_namespace_rules [optional, default=None]:

    An object (in the form {"namespace1":true/false, "namespace2":true/false}) that enables or disables metric collection for specific AWS namespaces for this AWS account only. A list of namespaces can be found at the /v1/integration/aws/available_namespace_rules endpoint.

Signature

PUT /v1/integration/aws

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# Update an AWS Account in Datadog

curl -X PUT \
  "https://api.datadoghq.com/api/v1/integration/aws?api_key=${api_key}&application_key=${app_key}&account_id=<YOUR_AWS_ACCOUNT_ID>&role_name=<ROLE_NAME>" \
  -H 'Content-Type: application/json' \
  -d '{
    "filter_tags": [
        "<TAG_KEY>:<TAG_VALUE>"
    ],
    "host_tags": [
        "<TAG_KEY>:<TAG_VALUE>"
    ],
    "account_specific_namespace_rules": {
        "auto_scaling": false,
        "opsworks": false
    }
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Delete an AWS integration

Delete a given Datadog-AWS integration.

Arguments
Signature

DELETE /v1/integration/aws

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# Delete an AWS Account in Datadog
curl -X DELETE -H "Content-type: application/json" \
-d '{
        "account_id": "<AWS_ACCOUNT_ID>",
        "role_name": "DatadogAWSIntegrationRole"
}' \
"https://api.datadoghq.com/api/v1/integration/aws?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

List Namespace rules

List all namespace rules for a given Datadog-AWS integration.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/aws/available_namespace_rules

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# List available namespace rules
curl -X GET "https://api.datadoghq.com/api/v1/integration/aws/available_namespace_rules?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
["api_gateway","application_elb","appsync","auto_scaling","billing","budgeting","cloudfront","cloudsearch","cloudwatch_events","cloudwatch_logs","codebuild","collect_custom_metrics","crawl_alarms","ddos_protection","directconnect","dms","documentdb","dynamodb","ebs","ec2","ec2api","ec2spot","ecs","efs","elasticache","elasticbeanstalk","elastictranscoder","elb","emr","es","firehose","gamelift","iot","kinesis","kinesis_analytics","kms","lambda","lex","ml","mq","nat_gateway","network_elb","opsworks","polly","rds","redshift","rekognition","route53","s3","sagemaker","ses","sns","sqs","state_machine","storage_gateway","swf","vpn","waf","workspaces","xray"]

Generate External IDs

Generate a new AWS external id for a given AWS account id and role name pair.

Arguments
Signature

PUT /v1/integration/aws/generate_new_external_id

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT -H "Content-type: application/json"
-d
  '{
    "account_id": "<YOUR_AWS_ACCOUNT_ID>",
    "role_name": "DatadogAWSIntegrationRole"
    }'

"https://dd.datadoghq.com/api/v1/integration/aws/generate_new_external_id?${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Get list of AWS log ready services

Get the list of current AWS services that Datadog offers automatic log collection. Use returned service IDs with the services parameter for the Enable an AWS service log collection API endpoint.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /aws/logs/services

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET "https://api.datadoghq.com/api/v1/integration/aws/logs/services?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Add AWS log lambda ARN

Attach the Lambda ARN of the Lambda created for the Datadog-AWS log collection to your AWS account ID to enable log collection.

ARGUMENTS
Signature

POST /v1/integration/aws/logs

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
        "account_id": "<AWS_ACCOUNT_ID>",
        "lambda_arn": "arn:aws:lambda:us-east-1:123456789012:function:PushLogs"
    }'\
"https://api.datadoghq.com/api/v1/integration/aws/logs?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Enable an AWS service log collection

Enable Automatic Log collection for your AWS services.

ARGUMENTS
Signature

POST /v1/integration/aws/logs/services

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
        "account_id": "<AWS_ACCOUNT_ID>",
        "services": ["elb","s3"]
    }'\
"https://api.datadoghq.com/api/v1/integration/aws/logs/services?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Delete AWS log collection

Delete a Datadog-AWS log collection configuration by removing the specific Lambda ARN associated with a given AWS account.

ARGUMENTS
Signature

DELETE /v1/integration/aws/logs

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X DELETE -H "Content-type: application/json" \
-d '{
        "account_id": "<AWS_ACCOUNT_ID>",
        "lambda_arn": "arn:aws:lambda:us-east-1:123456789012:function:PushLogs"
    }'\
"https://api.datadoghq.com/api/v1/integration/aws/logs?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Integration Azure

The Azure endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Configure your Datadog-Azure integration directly through the Datadog API. For more information, see the Datadog-Azure integration page.

List all Azure integrations

List all Datadog-Azure integrations configured for your organization.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/azure

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET "https://api.datadoghq.com/api/v1/integration/azure?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Create an Azure integration

Create a Datadog-Azure integration.

Note:

  • Using the POST method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization.
  • Using the PUT method updates your integration configuration by replacing your current configuration with the new one sent to your Datadog organization.
ARGUMENTS

Refer to the Datadog-Azure integration installation instructions to see how to obtain the following field values for your organization.

  • tenant_name [required]:

    Your Azure Active Directory ID.

  • client_id [required]:

    Your Azure web application ID.

  • client_secret [required]:

    Your Azure web application secret key.

  • host_filters [optional, default=None]:

    Limit the Azure instances that are pulled into Datadog by using tags. Only hosts that match one of the defined tags are imported into Datadog.

Signature

POST /v1/integration/azure

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# Create an Azure account in Datadog
curl -X POST -H "Content-type: application/json" \
-d '{
        "tenant_name": "<AZURE_TENANT_NAME>",
        "client_id": "<AZURE_CLIENT_ID>",
        "client_secret": "<AZURE_CLIENT_SECRET>",
        "host_filters": "<KEY_1>:<VALUE_1>,<KEY_2>:<VALUE_2>"
    }' \
"https://api.datadoghq.com/api/v1/integration/azure?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Delete an Azure integration

Delete a given Datadog-Azure integration.

Arguments

Refer to the Datadog-Azure integration installation instructions to see how to obtain the following field values for your organization.

  • tenant_name [required]:

    Your Azure Active Directory ID.

  • client_id [required]:

    Your Azure web application ID.

  • host_filters [optional, default=None]:

    Limit the Azure instances that are pulled into Datadog by using tags. Only hosts that match one of the defined tags are imported into Datadog.

Signature

DELETE /v1/integration/azure

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# Create an Azure account in Datadog
curl -X POST -H "Content-type: application/json" \
-d '{
        "tenant_name": "<AZURE_TENANT_NAME>",
        "client_id": "<AZURE_CLIENT_ID>",
        "client_secret": "<AZURE_CLIENT_SECRET>",
        "host_filters": "<KEY_1>:<VALUE_1>,<KEY_2>:<VALUE_2>"
    }' \
"https://api.datadoghq.com/api/v1/integration/azure?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Update an Azure integration host filters

Update the defined list of host filters for a given Datadog-Azure integration.

ARGUMENTS

Refer to the Datadog-Azure integration installation instructions to see how to obtain the following field values for your organization.

  • tenant_name [required]:

    Your Azure Active Directory ID.

  • client_id [required]:

    Your Azure web application ID.

  • client_secret [required]:

    Your Azure web application secret key.

  • host_filters [optional, default=None]:

    Limit the Azure instances that are pulled into Datadog by using tags. Only hosts that match one of the defined tags are imported into Datadog.

Signature

POST /v1/integration/azure/host_filters

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

# Create an Azure account in Datadog
curl -X POST -H "Content-type: application/json" \
-d '{
        "tenant_name": "<AZURE_TENANT_NAME>",
        "client_id": "<AZURE_CLIENT_ID>",
        "client_secret": "<AZURE_CLIENT_SECRET>",
        "host_filters": "<KEY_1>:<VALUE_1>,<KEY_2>:<VALUE_2>"
    }' \
"https://api.datadoghq.com/api/v1/integration/azure?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Integration GCP

The GCP endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Configure your Datadog-Google Cloud Platform (GCP) integration directly through the Datadog API. Read more about Datadog-Google Cloud Platform integration.

List all GCP integrations

List all Datadog-GCP integrations configured for your organization.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/gcp

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET "https://api.datadoghq.com/api/v1/integration/gcp?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Create a GCP integration

Create a Datadog-Google Cloud Platform integration.

Note:

  • Using the POST method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization.
  • Using the PUT method updates your integration configuration by replacing your current configuration with the new one sent to your Datadog organization.
ARGUMENTS

All of the following fields’ values are provided by the JSON service account key file created in the GCP Console for service accounts; Refer to the Datadog-Google Cloud Platform integration installation instructions to see how to generate one for your organization. For further references, consult the Google Cloud service account documentation.

  • type [required]:

    The value for service_account found in your JSON service account key.

  • project_id [required]:

    Your Google Cloud project ID found in your JSON service account key.

  • private_key_id [required]:

    Your private key ID found in your JSON service account key.

  • private_key [required]:

    Your private key name found in your JSON service account key.

  • client_email [required]:

    Your email found in your JSON service account key.

  • client_id [required]:

    Your ID found in your JSON service account key.

  • auth_uri [required]:

    Should be https://accounts.google.com/o/oauth2/auth.

  • token_uri [required]:

    Should be https://accounts.google.com/o/oauth2/token.

  • auth_provider_x509_cert_url [required]:

    Should be https://www.googleapis.com/oauth2/v1/certs.

  • client_x509_cert_url [required]:

    Should be https://www.googleapis.com/robot/v1/metadata/x509/<CLIENT_EMAIL> where <CLIENT_EMAIL> is the email found in your JSON service account key.

  • host_filters [optional]:

    Limit the GCE instances that are pulled into Datadog by using tags. Only hosts that match one of the defined tags are imported into Datadog.

  • automute [optional, default=false]:

    Silence monitors for expected GCE instance shutdowns.

Signature

POST /v1/integration/gcp

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
        "type": "service_account",
        "project_id": "<GCP_PROJECT_ID>",
        "private_key_id": "<PRIVATE_KEY_ID>",
        "private_key": "<PRIVATE_KEY>",
        "client_email": "<CLIENT_EMAIL>",
        "client_id": "<CLIENT_ID>",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://accounts.google.com/o/oauth2/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<CLIENT_EMAIL>",
        "host_filters": "<KEY_1>:<VALUE_1>,<KEY_2>:<VALUE_2>"
    }' \
"https://api.datadoghq.com/api/v1/integration/gcp?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Delete a GCP integration

Delete a given Datadog-GCP integration.

ARGUMENTS
  • project_id [required]:

    Your Google Cloud project ID found in your JSON service account key.

  • client_email [required]:

    Your email found in your JSON service account key.

Signature

DELETE /v1/integration/gcp

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X DELETE -H "Content-type: application/json" \
-d '{
        "project_id": "<GCP_PROJECT_ID>",
        "client_email": "<CLIENT_EMAIL>"
    }' \
"https://api.datadoghq.com/api/v1/integration/gcp?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Set GCP integration automute

Enable or disable automute for a given Datadog-GCP integration.

ARGUMENTS
  • project_id [required]:

    Your Google Cloud project ID found in your JSON service account key.

  • client_email [required]:

    Your email found in your JSON service account key.

  • automute [optional, default=false]:

    Silence monitors for expected GCE instance shutdowns.

Signature

PUT /v1/integration/gcp

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT -H "Content-type: application/json" \
-d '{
        "project_id": "<GCP_PROJECT_ID>",
        "client_email": "<CLIENT_EMAIL>",
        "automute": <AUTOMUTE> # true or false
    }' \
"https://api.datadoghq.com/api/v1/integration/gcp?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Integration PagerDuty

The PagerDuty endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Configure your Datadog-PagerDuty integration directly through the Datadog API. For more informations, see the PagerDuty integration page.

Get a PagerDuty integration

Get all information about your Datadog-PagerDuty integration.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/pagerduty

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X GET \
"https://api.datadoghq.com/api/v1/integration/pagerduty?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Create a PagerDuty integration

Create a new Datadog-PagerDuty integration.

Note: All arguments are required when creating (PUT) a new PagerDuty configuration.

ARGUMENTS
  • services : The array of PagerDuty service objects. Learn how to configure your Datadog service with the PagerDuty documentation. A PagerDuty service object is composed by:

    • service_name [required]: Your Service name in PagerDuty.

    • service_key [required]: Your Service name associated service key in Pagerduty.

  • subdomain : Your PagerDuty account’s personalized subdomain name.

  • schedules : Array of your schedule URLs, e.g: ["https://my-pd.pagerduty.com/schedules#PCPYT4M", "https://my-pd.pagerduty.com/schedules#PKTPB7P"]

  • api_token : Your PagerDuty API token.

Signature

PUT /v1/integration/pagerduty

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X PUT -H "Content-type: application/json" \
-d '{
      "services": [
        {
          "service_name": "<SERVICE_NAME_1>",
          "service_key": "<PAGERDUTY_SERVICE_KEY>"
        },
        {
          "service_name": "<SERVICE_NAME_2>",
          "service_key": "<PAGERDUTY_SERVICE_KEY>"
        }
      ],
      "subdomain": "<PAGERDUTY_SUB_DOMAIN>",
      "schedules": ["<SCHEDULE_1>", "<SCHEDULE_2>"],
      "api_token": "<PAGERDUTY_TOKEN>"
  }' \
"https://api.datadoghq.com/api/v1/integration/pagerduty?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Add new services and schedules

Add new services and schedules to your Datadog-PagerDuty integration.

Arguments
  • services : The array of PagerDuty service objects. Learn how to configure your Datadog service with the PagerDuty documentation. A PagerDuty service object is composed by:

    • service_name [required]: Your Service name in PagerDuty.

    • service_key [required]: Your Service name associated service key in Pagerduty.

  • schedules : The array of your schedule URLs: ["https://my-pd.pagerduty.com/schedules#PCPYT4M", "https://my-pd.pagerduty.com/schedules#PKTPB7P"]

Signature

POST /v1/integration/pagerduty

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X POST -H "Content-type: application/json" \
-d '{
      "services": [
        {
          "service_name": "test_00",
          "service_key": "<PAGERDUTY_SERVICE_KEY>"
        },
        {
          "service_name": "test_01",
          "service_key": "<PAGERDUTY_SERVICE_KEY>"
        }
      ],
      "schedules": ["<SCHEDULE_1>", "<SCHEDULE_2>"],
  }' \
"https://api.datadoghq.com/api/v1/integration/pagerduty?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Delete a PagerDuty integration

Delete the Datadog-PagerDuty integration.

Arguments

This endpoint takes no JSON arguments.

Signature

DELETE /v1/integration/pagerduty

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X DELETE \
"https://api.datadoghq.com/api/v1/integration/pagerduty?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Integration Slack

The Slack endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Configure your Datadog-Slack integration directly through Datadog API. For more information about the Datadog-Slack integration, see the integration page.

Get Slack integration

Get all information about your Datadog-Slack integration.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/slack

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X GET "https://api.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Create a Slack integration

Create a Datadog-Slack integration. Once created, add a channel to it with the Add channels to Slack integration endpoint.

Note:

  • Using the POST method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization.
  • Using the PUT method updates your integration configuration by replacing your current configuration with the new one sent to your Datadog organization.
ARGUMENTS
  • service_hooks [required]: Array of service hook objects (the service hook is generated for your slack account in your Slack account administration page). A service hook object is composed by:

    • account [required]: Your Slack account name.

    • url [required]: Your Slack Service Hook URL.

Note: service_hooks are not required in the payload when adding (POST) or updating (PUT) an existing Slack configuration.

Signature

POST /v1/integration/slack

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X POST -H "Content-type: application/json" \
-d '{
    "service_hooks": [
      {
        "account": "Main_Account",
        "url": "https://hooks.slack.com/services/1/1/1"
      },
      {
        "account": "doghouse",
        "url": "https://hooks.slack.com/services/2/2/2"
      }
    ]
  }' \
"https://api.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Add channels to Slack integration

Add channels to your Datadog-Slack integration.

ARGUMENTS
  • channels [required]: The array of slack channel objects to post to. A slack channel object is composed by:

    • channel_name [required]: Your channel name e.g: #general, #private

    • transfer_all_user_comments [optional, default=False]: To be notified for every comment on a graph, set it to true. If set to False use the @slack-channel_name syntax for comments to be posted to slack.

    • account [required]: Account to which the channel belongs to.

Signature

POST /v1/integration/slack

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
    "channels": [
        {
          "channel_name": "#channel_name_main_account",
          "transfer_all_user_comments": "false",
          "account": "Main_Account"
        },
        {
          "channel_name": "#channel_name_doghouse",
          "transfer_all_user_comments": "false",
          "account": "doghouse"
        }
    ]
}' \
"https://api.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Delete a Slack integration

Delete a Datadog-Slack integration.

Arguments

This endpoint takes no JSON arguments.

Signature

DELETE /v1/integration/slack

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X DELETE "https://api.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Integration Webhooks

The Webhooks endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Configure your Datadog-Webhooks integration directly through the Datadog API. For more information about the Datadog-Webhooks integration, see the integration page.

Get a Webhooks Integration

Get all Datadog-Webhooks integration information.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/integration/webhooks

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X GET "https://api.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Create a Webhooks Integration

Create a Datadog-Webhooks integration.

Note:

  • Using the POST method updates your integration configuration by adding your new configuration to the existing one in your Datadog organization.
ARGUMENTS
  • hooks [required]: Array of Webhook objects. A Webhook object is composed by:

    • name [required]: Your Webhook name. Learn more on how to use it in monitor notifications.
    • url [required]: Your Webhook URL.
    • use_custom_payload [optional, default=False]: If true, allow you to specify a custom payload for your Webhook.

    • custom_payload [optional, default=None]: If use_custom_payload is true, specify your own payload to add your own custom fields to the request using those variables.

    • encode_as_form [optional, default=False]: If use_custom_payload is true, set this to true to have your payload to be URL-encoded.

    • headers [optional, default=None]: Headers attached to your Webhook.

Signature

POST /v1/integration/webhooks

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X POST -H "Content-type: application/json" \
-d '{
    "hooks": [
      {
        "name": "<WEBHOOK_NAME>",
        "url": "<WEBHOOK_URL>",
        "use_custom_payload": "false",
        "encode_as_form": "false"
      }
    ]
}' \
"https://api.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Add a Webhook to a Webhooks Integration

Add a specific Webhook to a Datadog Webhooks integration.

Arguments
  • hooks [required]: Array of Webhook objects. A Webhook object is composed by:

    • name [required]: Your Webhook name. Learn more on how to use it in monitor notifications.
    • url [required]: Your Webhook URL.
    • use_custom_payload [optional, default=False]: If true, allow you to specify a custom payload for your Webhook.

    • custom_payload [optional, default=None]: If use_custom_payload is true, specify your own payload to add your own custom fields to the request using those variables.

    • encode_as_form [optional, default=False]: If use_custom_payload is true, set this to true to have your payload to be URL-encoded.

    • headers [optional, default=None]: Headers attached to your Webhook.

Signature

POST /v1/integration/webhooks

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X POST -H "Content-type: application/json" \
-d '{
    "hooks": [
      {
        "name": "<WEBHOOK_NAME>",
        "url": "<WEBHOOK_URL>"
      }
    ]
}' \
"https://api.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Delete a Webhooks Integration

Delete a given Datadog-Webhooks integration.

Arguments

This endpoint takes no JSON arguments.

Signature

DELETE /v1/integration/webhooks

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -v -X DELETE "https://api.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
OK

Key Management

The Key Management endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Manage your Datadog API and application keys.

You need an API and applications key with Admin rights to interact with this endpoint.

The full list of keys can be seen on your Datadog API page.

Get all API Keys

Get all API keys available for your account.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/api_key/

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://app.datadoghq.com/api/v1/api_key?api_key=${api_key}}&application_key=${app_key}" \
  -H 'Content-Type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "api_keys": [
        {
            "created_by": "john@example.com",
            "name": "<API_KEY_NAME>",
            "key": "1111111111111111aaaaaaaaaaaaaaaa",
            "created": "2019-04-05 09:20:30"
        },
        {
            "created_by": "jane@example.com",
            "name": "<APP_KEY_NAME_2>",
            "key": "2111111111111111aaaaaaaaaaaaaaaa",
            "created": "2019-04-05 09:19:53"
        }
    ]
}

Get an API Key

Get a given API key.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/api_key/<API_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://app.datadoghq.com/api/v1/api_key/<API_KEY_TO_GET>?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "api_key": {
        "created_by": "john@example.com",
        "name": "<API_KEY_NAME>",
        "key": "3111111111111111aaaaaaaaaaaaaaaa",
        "created": "2019-04-05 09:47:00"
    }
}

Create an API Key

Create an API key with a given name.

ARGUMENTS
  • name [required]:

    Name of your API key.

Signature

POST /v1/api_key/<API_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST \
  "https://app.datadoghq.com/api/v1/api_key?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "<API_KEY_NAME>"
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "api_key": {
        "created_by": "john@example.com",
        "name": "<API_KEY_NAME>",
        "key": "3111111111111111aaaaaaaaaaaaaaaa",
        "created": "2019-04-05 09:47:00"
    }
}

Edit an API Key

Edit an API key name.

ARGUMENTS
  • name [required]:

    Name of your API key.

Signature

PUT /v1/api_key/<API_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT \
  "https://app.datadoghq.com/api/v1/api_key/<API_KEY_TO_EDIT>?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"<NEW_API_KEY_NAME>"
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "api_key": {
        "created_by": "john@example.com",
        "name": "<API_KEY_NAME>",
        "key": "3111111111111111aaaaaaaaaaaaaaaa",
        "created": "2019-04-05 09:47:00"
    }
}

Delete an API Key

Delete a given API key.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

DELETE /v1/api_key/<API_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X DELETE \
  "https://app.datadoghq.com/api/v1/api_key/<API_KEY_TO_DELETE>?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "api_key": {
        "created_by": "john@example.com",
        "name": "<API_KEY_NAME>",
        "key": "3111111111111111aaaaaaaaaaaaaaaa",
        "created": "2019-04-05 09:47:00"
    }
}

Get all Application Keys

Get all application keys available for your account.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/application_key/

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://app.datadoghq.com/api/v1/application_key?api_key=${api_key}}&application_key=${app_key}" \
  -H 'Content-Type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "application_keys": [
        {
            "owner": "john@example.com",
            "hash": "11111111111111111111aaaaaaaaaaaaaaaaaaaa",
            "name": "<APP_KEY_NAME>"
        },
        {
            "owner": "jane@example.com",
            "hash": "21111111111111111111aaaaaaaaaaaaaaaaaaaa",
            "name": "<APP_KEY_NAME_2>"
        }
    ]
}

Get an Application Key

Get a given application key.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/application_key/<APP_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://app.datadoghq.com/api/v1/application_key/<APP_KEY_TO_GET>?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "application_key": {
        "owner": "john@example.com",
        "hash": "31111111111111111111aaaaaaaaaaaaaaaaaaaa",
        "name": "<APP_KEY_NAME>"
    }
}

Create an Application Key

Create an application key with a given name.

ARGUMENTS
  • name [required]:

    Name of your application key.

Signature

POST /v1/application_key/<APP_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST \
  "https://app.datadoghq.com/api/v1/application_key?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "<APP_KEY_NAME>"
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "application_key": {
        "owner": "john@example.com",
        "hash": "31111111111111111111aaaaaaaaaaaaaaaaaaaa",
        "name": "<APP_KEY_NAME>"
    }
}

Edit an application Key

Edit an application key name.

ARGUMENTS
  • name [required]:

    Name of your application key.

Signature

PUT /v1/application_key/<APP_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT \
  "https://app.datadoghq.com/api/v1/application_key/<APP_KEY_TO_EDIT>?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"<NEW_APP_KEY_NAME>"
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "application_key": {
        "owner": "john@example.com",
        "hash": "31111111111111111111aaaaaaaaaaaaaaaaaaaa",
        "name": "<NEW_APP_KEY_NAME>"
    }
}

Delete an Application Key

Delete a given application key.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

DELETE /v1/application_key/<APP_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X DELETE \
  "https://app.datadoghq.com/api/v1/application_key/<APP_KEY_TO_DELETE>?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "application_key": {
        "owner": "john@example.com",
        "hash": "31111111111111111111aaaaaaaaaaaaaaaaaaaa",
        "name": "<APP_KEY_NAME>"
    }
}

Logs

The Logs endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Send your logs to your Datadog platform over HTTP. Limits per HTTP request are:

  • Maximum content size per payload: 5MB
  • Maximum size for a single log: 256kB
  • Maximum array size if sending multiple logs in an array: 200 entries

Note: If you are in the Datadog EU site (app.datadoghq.eu), the HTTP log endpoint is: http-intake.logs.datadoghq.eu.

Send Logs over HTTP

ItemDescription
Protocolhttp: 80
https: 443
HostFor Datadog US: http-intake.logs.datadoghq.com
For Datadog EU: http-intake.logs.datadoghq.eu
Path/v1/input/<DATADOG_API_KEY>
Query parametersQuery parameters available are the reserved log attribute. ?ddtags=<TAGS>&ddsource=<SOURCE>&service=<SERVICE>&hostname=<HOSTNAME>
MethodPOST
Content TypeAvailable content type are: text/plain, application/json, application/logplex-1
Signature

https://http-intake.logs.datadoghq.com/v1/input/<DATADOG_API_KEY>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
## Simple Raw Message
## Log attributes can be passed as query parameters

curl -X POST https://http-intake.logs.datadoghq.com/v1/input/<API_KEY>?ddtags=env:prod,user:my-user \
     -H "Content-Type: text/plain" \
     -d 'hello world'

## Multi Raw Messages

curl -X POST https://http-intake.logs.datadoghq.com/v1/input/<API_KEY> \
     -H "Content-Type: text/plain" \
     --data-binary @- <<BODY
hello
world
BODY

## Simple JSON Message
## Log attributes can also be passed as key:value pairs in valid JSON messages
curl -X POST https://http-intake.logs.datadoghq.com/v1/input/<API_KEY> \
     -H "Content-Type: application/json" \
     -d '{"message":"hello world", "ddsource":"<SOURCE>", "ddtags":"env:<ENV>,user:<USER_NAME>", "hostname":"<HOSTNAME>"}'

## Multi JSON Messages

curl -X POST https://http-intake.logs.datadoghq.com/v1/input/<API_KEY> \
     -H "Content-Type: application/json" \
     --data-binary @- <<BODY
[
  {
    "message": "hello"
  },
  {
    "message": "world"
  }
]
BODY

## Simple Logplex Message

curl -X POST https://http-intake.logs.datadoghq.com/v1/input/<API_KEY> \
     -H "Content-Type: application/logplex-1" \
     -d 'hello world'

## Multi Logplex Messages

curl -X POST https://http-intake.logs.datadoghq.com/v1/input/<API_KEY> \
     -H "Content-Type: application/logplex-1" \
     --data-binary @- <<BODY
hello
world
BODY
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Get a list of logs

List endpoint returns logs that match a log search query. Results are paginated.

If you are thinking about archiving logs for your organization, consider using Datadog archive capabilities instead of the log list API. See Datadog Logs Archive documentation.

ARGUMENTS
  • query [required]: The search query - following the Log search syntax .
  • time.from [required]: Minimum timestamp for requested logs. Format can be either
    • an ISO-8601 string
    • a unix timestamp (number representing the elapsed millisec since epoch)
    • a relative time (now -10m, now - 1h, now - 1d)
  • time.to [required]: Maximum timestamp for requested logs. Format can be either
    • an ISO-8601 string with minute, second or millisecond precision
    • a unix timestamp (number representing the elapsed millisec since epoch)
    • a relative time (now, now -10m, now - 1h, now - 1d)
  • time.timezone [optional, default=None]: Can be specified both as an offset (e.g. “UTC+03:00”) or a regional zone (e.g. “Europe/Paris”)
  • time.offset [optional, default=None]: Equivalent to time.timezone. But value in seconds. If both timezone and offset are specified, timezone is ignored.
  • startAt [optional, default=None]: Hash identifier of the first log to return in the list, available in a log id attribute. This parameter is used for the pagination feature. Note: this parameter is ignored if the corresponding log is out of the scope of the specified time window.
  • sort [optional, default=desc]: Time-ascending asc or time-descending descresults.
  • limit [optional, default=10]: Number of logs return in the response (maximum is 1000)
  • index [optional, default=main]: For multi-index organizations, the log index in which the request is performed.
Signature

POST api/v1/logs-queries/list

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST \
  "https://api.datadoghq.com/api/v1/logs-queries/list?api_key=${api_key}&application_key=${app_key}" \
  -H 'content-type: application/json' \
  -d '{"query": "service:nginx -@http.method:POST","time": {"from": "now - 1h", "to": "now"}, "sort": "desc", "limit": 50}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    logs: [{
        id: "AAAAAWgN8Xwgr1vKDQAAAABBV2dOOFh3ZzZobm1mWXJFYTR0OA",
        content: {
            timestamp: "2019-01-02T09:42:36.320Z",
            tags: ['team:A'],
            attributes: {
                customAttribute: 123,
                duration: 2345
            },
            host: 'i-123',
            service: 'agent',
            message: 'host connected to remote'
        }
    }],
    nextLogId: "BBBBWgn...",
    status: "ok"
}

Logs Indexes

This endpoint is in public beta and not supported in Datadog's client libraries. If you have any feedback, contact Datadog support.

The Index object describes the configuration of a log index. It has the following attributes:

  • name (Read Only): The name of the index.
  • filter.query : Only logs matching the filter criteria are considered for this index. The search query followis the Log search syntax
  • num_retention_days (Read Only) : The number of days before logs are deleted from this index
  • daily_limit (Read Only) : The number of log-events you can send in this index before you are rate-limited.
  • is_rate_limited (Read Only) : A boolean stating if the index is rate limited, meaning more logs than the daily limit have been sent. Rate limit is reset every-day at 2pm UTC.
  • exclusion_filters An array of ExclusionFilter objects (see hereafter). The logs are tested against the query of each ExclusionFilter, following the order of the array. Only the first matching active ExclusionFilter matters, others (if any) are ignored.

    • name : The name of the exclusion filter
    • is_enabled : A boolean stating if the exclusion is active (will eventually exclude logs) or not.
    • filter.query : Only logs matching the filter criteria AND the query of the parent index will be considered for this exclusion filter. The search query follows the Log search syntax
    • filter.sample_rate : The fraction of logs excluded by the exclusion filter, when active. The sampling is uniform.

Note: You need an API and applications key with Admin right to interact with this endpoint.

Get all Indexes

This endpoint is in public beta. If you have any feedback, contact Datadog support.

This endpoint returns an array of the Index objects of your organization.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/logs/config/indexes/

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://api.datadoghq.com/api/v1/logs/config/indexes?api_key=${api_key}&application_key=${app_key}" \
  -H 'content-type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
  "indexes": [
      {
        "name": "<INDEX_NAME>",
        "filter": {
            "query": "<INDEX_FILTER_QUERY>"
        },
        "num_retention_days": 15,
        "daily_limit": 150000000,
        "is_rate_limited": false,
        "exclusion_filters": [
            {
                "name": "<INDEX_EXCLUSTION_FILTER_1>",
                "is_enabled": true,
                "filter": {
                    "query": "<INDEX_EXCLUSTION_FILTER_QUERY>",
                    "sample_rate": 1
                }
            }
        ]
    }
  ]
}

Get an Index

This endpoint is in public beta. If you have any feedback, contact Datadog support.

This endpoint returns an Index identified by its name.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/logs/config/indexes/<INDEX_NAME>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://api.datadoghq.com/api/v1/logs/config/indexes/<INDEX_NAME>?api_key=${api_key}&application_key=${app_key}" \
  -H 'content-type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
	"name": "<INDEX_NAME>",
	"filter": {
		"query": "<INDEX_FILTER_QUERY>"
	},
	"num_retention_days": 15,
	"daily_limit": 150000000,
	"is_rate_limited": false,
	"exclusion_filters": [
		{
			"name": "<INDEX_EXCLUSTION_FILTER_1>",
			"is_enabled": true,
			"filter": {
				"query": "<INDEX_EXCLUSTION_FILTER_QUERY>",
				"sample_rate": 1
			}
		}
	]
}

Update an Index

This endpoint is in public beta. If you have any feedback, contact Datadog support.

This endpoint updates an Index identified by its name. It returns the Index object passed in the request body when the request is successful.

Arguments
  • filter.query [optional]: Only logs matching the filter criteria will be considered for this index. The search query followis the Log search syntax
  • exclusion_filters An array of ExclusionFilter objects (see hereafter). The logs are tested against the query of each ExclusionFilter, following the order of the array. Only the first matching active ExclusionFilter matters, others (if any) are ignored. The ExclusionFilter object describes the configuration of an exclusion filter. It has the following attributes:

    • name [required]: The name of the exclusion filter
    • is_enabled [optional, default=False]: A boolean stating if the exclusion is active.
    • filter.query [optional]: Only logs matching the filter criteria AND the query of the parent index will be considered for this exclusion filter. The search query follows the Log search syntax
    • filter.sample_rate [required]: The fraction of logs excluded by the exclusion filter, when active. The sampling is uniform.
Signature

PUT /v1/logs/config/indexes/<INDEX_NAME>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT \
  "https://api.datadoghq.com/api/v1/logs/config/indexes/<INDEX_NAME>?api_key=${api_key}&application_key=${app_key}" \
  -H 'content-type: application/json' \
  -d '{
    "filter": {
        "query": "<NEW_INDEX_FILTER_QUERY>"
    },
    "exclusion_filters": [
      {
        "name": "<INDEX_EXCLUSTION_FILTER_1>",
        "is_enabled": true,
        "filter": {
          "query": "<INDEX_EXCLUSTION_FILTER_QUERY>",
          "sample_rate": 1
        }
      },
      {
        "name": "<INDEX_EXCLUSTION_FILTER_2>",
        "is_enabled": true,
        "filter": {
          "query": "<INDEX_EXCLUSTION_FILTER_QUERY_2>",
          "sample_rate": 1
        }
      }
    ]
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
	"name": "<INDEX_NAME>",
	"filter": {
		"query": "<NEW_INDEX_FILTER_QUERY>"
	},
	"num_retention_days": 15,
	"daily_limit": 150000000,
	"is_rate_limited": false,
	"exclusion_filters": [
		{
        "name": "<INDEX_EXCLUSTION_FILTER_1>",
        "is_enabled": true,
        "filter": {
          "query": "<INDEX_EXCLUSTION_FILTER_QUERY>",
          "sample_rate": 1
        }
      },
      {
        "name": "<INDEX_EXCLUSTION_FILTER_2>",
        "is_enabled": true,
        "filter": {
          "query": "<INDEX_EXCLUSTION_FILTER_QUERY_2>",
          "sample_rate": 1
        }
      }
	]
}

Get Indexes Order

This endpoint is in public beta. If you have any feedback, contact Datadog support.

Use the index order endpoints to control the processing order of an organization’s indexes. Use this endpoint only if you have more than one index for logs in your organization. Note that this index cannot be used to add or delete indexes.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/logs/config/index-order

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET \
  "https://api.datadoghq.com/api/v1/logs/config/index-order?api_key=${api_key}&application_key=${app_key}" \
  -H 'content-type: application/json'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
	"index_names": [
		"<INDEX_NAME_1>",
		"<INDEX_NAME_2>"
	]
}

Update Indexes Order

This endpoint is in public beta. If you have any feedback, contact Datadog support.

This endpoint updates the IndexOrder of your organization. It returns the IndexOrder object passed in the request body when the request is successful.

Arguments
  • index_names [required]: Array of Strings identifying by their name(s) the index(es) of your organisation. Logs are tested against the query filter of each index one by one, following the order of the array. Logs are eventually stored in the first matching index.
Signature

PUT /v1/logs/config/index-order

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT \
  "https://api.datadoghq.com/api/v1/logs/config/index-order?api_key=${api_key}&application_key=${app_key}" \
  -H 'content-type: application/json' \
  -d '{
	"index_names": [
    "<INDEX_NAME_2>",
		"<INDEX_NAME_1>"
	]
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
	"index_names": [
        "<INDEX_NAME_2>",
		"<INDEX_NAME_1>"
	]
}

Logs Pipelines

The Logs Pipelines endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Pipelines and processors operate on incoming logs, parsing and transforming them into structured attributes for easier querying.

Note: These endpoints are only available for admin users. Make sure to use an application key created by an admin.

Get Pipeline Order

Get the current order of your pipelines.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/logs/config/pipeline-order

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET "https://api.datadoghq.com/api/v1/logs/config/pipeline-order?api_key=${api_key}&application_key=${app_key}"
Example Response

Update Pipeline Order

Update the order of your Pipelines.

Note: Logs are processed sequentially. Reordering a pipeline may change the structure and content of the data processed by other pipelines and their processors.

Arguments
  • pipeline_ids [required]: Ordered Array of <PIPELINE_ID> strings, the order of pipeline IDs in the array define the overall Pipelines order for Datadog?
Signature

PUT /v1/logs/config/pipeline-order

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X PUT "https://api.datadoghq.com/api/v1/logs/config/pipeline-order?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
    "pipeline_ids": [
        "<PIPELINE_1_ID>",
        "<PIPELINE_2_ID>",
        "<PIPELINE_3_ID>"
    ]
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "pipeline_ids": [
        "<PIPELINE_1_ID>",
        "<PIPELINE_2_ID>",
        "<PIPELINE_3_ID>"
    ]
}

Get all Pipelines

Get all pipelines from your organization.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/logs/config/pipelines

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X GET "https://api.datadoghq.com/api/v1/logs/config/pipelines?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
[
    {
        "id": "<PIPELINE_1_ID>",
        "type": "pipeline",
        "name": "<PIPELINE_1_NAME>",
        "is_enabled": false,
        "is_read_only": true,
        "filter": {
            "query": "<PIPELINE_1_FILTER>"
        },
        "processors": ["<PROCESSOR_PIPELINE_1ARRAY>"
        ]
    },
    {
        "id": "<PIPELINE_2_ID>",
        "type": "pipeline",
        "name": "<PIPELINE_2_NAME>",
        "is_enabled": false,
        "is_read_only": true,
        "filter": {
            "query": "<PIPELINE_2_FILTER>"
        },
        "processors": ["<PROCESSOR_PIPELINE_2_ARRAY>"
        ]
    }
]

Get a Pipeline

Get a specific pipeline from your organization.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/logs/config/pipelines/<PIPELINE_ID>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>
pipeline_id=<PIPELINE_ID>

curl -X GET "https://api.datadoghq.com/api/v1/logs/config/${pipeline_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "id": "<PIPELINE_ID>",
    "type": "pipeline",
    "name": "<PIPELINE_NAME>",
    "is_enabled": false,
    "is_read_only": true,
    "filter": {
        "query": "<PIPELINE_FILTER>"
    },
    "processors": [
        {
            "name": "<PROCESSOR_1_NAME>",
            "is_enabled": true,
            "source": "message",
            "grok": {
                "support_rules": "",
                "match_rules": "<MATCHED_RULES>"
            },
            "type": "grok-parser"
        },
        {
            "name": "Define timestamp as the official timestamp of the log",
            "is_enabled": true,
            "sources": [
                "timestamp"
            ],
            "type": "date-remapper"
        },
        {
            "name": "Define level as the official log status",
            "is_enabled": true,
            "sources": [
                "level"
            ],
            "type": "status-remapper"
        }
    ]
}

Create a Pipeline

Create a Pipeline in your organization.

Arguments
  • name [required]: Your pipeline name.

  • is_enabled [optional, default=False]: Boolean value to enable your pipeline.

  • filter.query [optional]: Defines your pipeline filter. Only logs that match the filter criteria are processed by this pipeline.

  • processors [optional]: Ordered array of processors or nested pipelines. See the Processor documentation to get the specific Scheme for each processor.

Signature

POST /v1/logs/config/pipelines

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>

curl -X POST \
  "https://api.datadoghq.com/api/v1/logs/config/pipelines?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<PIPELINE_NAME>",
    "is_enabled": true,
    "filter": {
        "query": "<PIPELINE_QUERY>"
    },
    "processors": [
        {
            "name": "Define date as the official timestamp of the log",
            "is_enabled": true,
            "sources": [
                "date"
            ],
            "type": "date-remapper"
        }
    ]
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "id": "7fKHTENgSkyGoJcCDbem-g",
    "type": "pipeline",
    "name": "<PIPELINE_NAME>",
    "is_enabled": true,
    "is_read_only": false,
    "filter": {
        "query": "<PIPELINE_QUERY>"
    },
    "processors": [
        {
            "name": "Define date as the official timestamp of the log",
            "is_enabled": true,
            "sources": [
                "date"
            ],
            "type": "date-remapper"
        }
    ]
}

Update a Pipeline

Update a given pipeline configuration to change it’s processors or their order.

Arguments
  • name [required]: Your pipeline name.

  • is_enabled [optional, default=False]: Boolean value to enable your pipeline.

  • filter.query [optional]: Defines your pipeline filter. Only logs that match the filter criteria are processed by this pipeline.

  • processors [optional]: Ordered array of processors or nested pipelines. See the Processor documentation to get the specific scheme for each processor.

Signature

PUT /v1/logs/config/pipelines/<PIPELINE_ID>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>
pipeline_id=<PIPELINE_ID>

curl -X PUT \
  "https://api.datadoghq.com/api/v1/logs/config/pipelines/${pipeline_id}?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<NEW_PIPELINE_NAME>",
    "is_enabled": true,
    "filter": {
        "query": "<NEW_PIPELINE_QUERY>"
    },
    "processors": [
        {
            "name": "Define date as the official timestamp of the log",
            "is_enabled": true,
            "sources": [
                "date"
            ],
            "type": "date-remapper"
        }
    ]
}'
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
    "id": "<PIPELINE_ID>",
    "type": "pipeline",
    "name": "<NEW_PIPELINE_NAME>",
    "is_enabled": true,
    "is_read_only": false,
    "filter": {
        "query": "<NEW_PIPELINE_QUERY>"
    },
    "processors": [
        {
            "name": "Define date as the official timestamp of the log",
            "is_enabled": true,
            "sources": [
                "date"
            ],
            "type": "date-remapper"
        }
    ]
}

Delete a Pipeline

Delete a given pipeline from your Organization.

Arguments

This endpoint takes no JSON arguments.

Signature

DELETE /v1/logs/config/pipelines

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Make sure you replace the <DD_API_KEY> and <DD_APP_KEY> key below
# with the ones for your account

api_key=<DD_API_KEY>
app_key=<DD_APP_KEY>
pipeline_id=<PIPELINE_ID>

curl -X DELETE "https://api.datadoghq.com/api/v1/logs/config/pipelines/${pipeline_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{}

Metrics

The metrics end-point allows you to:

  • Post metrics data so it can be graphed on Datadog’s dashboards
  • Query metrics from any time period

As occurs within the Datadog UI, a graph can only contain a set number of points and as the timeframe over which a metric is viewed increases, aggregation between points occurs to stay below that set number.

Thus, if you are querying for larger timeframes of data, the points returned is more aggregated. The max granularity within Datadog is one point per second, so if you had submitted points at that interval and requested a very small interval from the query API (in this case, probably less than 100 seconds), you could end up getting all of those points back. Otherwise, Datadog algorithm tries to return about 150 points per any given time window, so you’ll see coarser and coarser granularity as the amount of time requested increases. We do this time aggregation via averages.

We store metric points at the 1 second resolution, but we’d prefer if you only submitted points every 15 seconds. Any metrics with fractions of a second timestamps gets rounded to the nearest second, and if any points have the same timestamp, the latest point overwrites the previous ones.

We have a soft limit of 100 timeseries per host, where a timeseries is defined as a unique combination of metric name and tag.

Get list of active metrics

This endpoint is not supported in Datadog’s Ruby client library. To request this functionality, contact Datadog Support.

Get the list of actively reporting metrics from a given time until now. This endpoint is not available in the Python and Ruby libraries.

ARGUMENTS
  • from [required]: Seconds since the Unix epoch
  • host [optional]: Hostname for filtering the list of metrics returned. If set, metrics retrieved are those with the corresponding hostname tag.
Signature

GET /v1/metrics

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Taking the last 24hours
from_time = int(time.time()) - 60 * 60 * 24 * 1

result = api.Metric.list(from_time)

print(result)
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

from_time=$(date -v -1d +%s)

curl -G \
    "https://api.datadoghq.com/api/v1/metrics" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "from=${from_time}" \
    -d "host=<HOSTNAME>"
Example Response
{
    "metrics": [
        "system.load.1",
        "system.load.15",
        "system.load.5",
        "system.load.norm.1",
        "system.load.norm.15",
        "system.load.norm.5",
        "system.mem.buffered",
        "system.mem.cached",
        "system.mem.committed",
        "system.mem.free"
    ],
    "from": 1467815773
}
{
    "metrics": [
        "system.load.1",
        "system.load.15",
        "system.load.5",
        "system.load.norm.1",
        "system.load.norm.15",
        "system.load.norm.5",
        "system.mem.buffered",
        "system.mem.cached",
        "system.mem.committed",
        "system.mem.free"
    ],
    "from": 1467815773
}
{
  "metrics": [
    "system.load.1",
    "system.load.15",
    "system.load.5",
    "system.load.norm.1",
    "system.load.norm.15",
    "system.load.norm.5",
    "system.mem.buffered",
    "system.mem.cached",
    "system.mem.committed",
    "system.mem.free"
  ],
  "from": 1467815773
}

Post timeseries points

The metrics end-point allows you to post time-series data that can be graphed on Datadog’s dashboards. The limit for compressed payloads is 3.2 megabytes (3200000), and 62 megabytes (62914560) for decompressed payloads.

ARGUMENTS

  • series [required]: Pass a JSON array where each item in the array contains the following arguments:

    • metric [required]: The name of the timeseries
    • type [optional, default=gauge]: Type of your metric either: gauge, rate, or count
    • interval [optional, default=None]: If the type of the metric is rate or count, define the corresponding interval.
    • points [required]: A JSON array of points. Each point is of the form: [[POSIX_timestamp, numeric_value], ...] Note: The timestamp should be in seconds, current. The numeric value format should be a 32bit float gauge-type value. Current is defined as not more than 10 minutes in the future or more than 1 hour in the past.
    • host [optional]: The name of the host that produced the metric.
    • tags [optional, default=None]: A list of tags associated with the metric.
Signature

POST /v1/series

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>'
}

initialize(**options)

now = time.time()
future_10s = now + 10

# 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=(now, 15))

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

# Submit a point with a host and tags.
api.Metric.send(
    metric='my.series',
    points=100,
    host="myhost.example.com",
    tags=["version:1"]
)

# Submit multiple metrics
api.Metric.send([{
    'metric': 'my.series',
    'points': 15
}, {
    'metric': 'my1.series',
    'points': 16
}])
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'

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"])

# Emit differents metrics in a single request to be more efficient
dog.batch_metrics do
  dog.emit_point('test.api.test_metric',10)
  dog.emit_point('test.api.this_other_metric', 1)
end


currenttime=$(date +%s)

curl  -X POST -H "Content-type: application/json" \
-d "{ \"series\" :
         [{\"metric\":\"test.metric\",
          \"points\":[[$currenttime, 20]],
          \"type\":\"rate\",
          \"interval\": 20,
          \"host\":\"test.example.com\",
          \"tags\":[\"environment:test\"]}
        ]
}" \
"https://api.datadoghq.com/api/v1/series?api_key=<YOUR_API_KEY>"

Query timeseries points

This endpoint allows you to query for metrics from any time period. Use the query syntax described in From the query to the graph.

Note: In Python, from is a reserved word. So instead, the Python API uses the start and end parameters in the function call.

ARGUMENTS
  • from [required except in Python]: Seconds from the unix epoch
  • to [required except in Python]: Seconds to the unix epoch
  • start [required in Python, default=None]: Seconds since the unix epoch
  • end [required in Python, default=None]: Seconds since the unix epoch
  • query [required]: The query string
Signature

GET /v1/query

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

now = int(time.time())

query = 'system.cpu.idle{*}by{host}'
print api.Metric.query(start=now - 3600, end=now, query=query)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Get points from the last hour
from = Time.now - 3600
to = Time.now
query = 'system.cpu.idle{*}by{host}'

dog.get_points(query, from, to)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
to_time=$(date +%s)
from_time=$(date -v -1d +%s)

curl -G \
    "https://api.datadoghq.com/api/v1/query" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "from=${from_time}" \
    -d "to=${to_time}" \
    -d "query=system.cpu.idle{*}by{host}"
Example Response
{
    'status': 'ok',
    'res_type': 'time_series',
    'series': [{
        'end': 1430313599000,
        'metric': 'system.cpu.idle',
        'interval': 30,
        'start': 1430312070000,
        'length': 10,
        'aggr': None,
        'attributes': {},
        'pointlist': [
            [1430312070000.0, 75.08000183105469],
            [1430312100000.0, 99.33000183105469],
            [1430312130000.0, 99.83499908447266],
            [1430312160000.0, 100.0],
            [1430312190000.0, 99.66999816894531],
            [1430312220000.0, 100.0],
            [1430312250000.0, 99.83499908447266],
            [1430312280000.0, 99.66999816894531],
            [1430312310000.0, 99.83499908447266],
            [1430312340000.0, 99.66999816894531]
        ],
        'expression': 'system.cpu.idle{host:vagrant-ubuntu-trusty-64}',
        'scope': 'host:vagrant-ubuntu-trusty-64',
        'unit': None,
        'display_name': 'system.cpu.idle'
    }],
    'from_date': 1430309983000,
    'group_by': ['host'],
    'to_date': 1430313583000,
    'query': 'system.cpu.idle{*}by{host}',
    'message': u''
}
{
    'status' => 'ok',
    'res_type' => 'time_series',
    'series' => [{
        'end' => 1430313599000,
        'metric' => 'system.cpu.idle',
        'interval' => 30,
        'start' => 1430312070000,
        'length' => 10,
        'aggr' => nil,
        'attributes' => {},
        'pointlist' => [
            [1430312070000.0, 75.08000183105469],
            [1430312100000.0, 99.33000183105469],
            [1430312130000.0, 99.83499908447266],
            [1430312160000.0, 100.0],
            [1430312190000.0, 99.66999816894531],
            [1430312220000.0, 100.0],
            [1430312250000.0, 99.83499908447266],
            [1430312280000.0, 99.66999816894531],
            [1430312310000.0, 99.83499908447266],
            [1430312340000.0, 99.66999816894531]
        ],
        'expression' => 'system.cpu.idle{host:vagrant-ubuntu-trusty-64}',
        'scope' => 'host:vagrant-ubuntu-trusty-64',
        'unit' => nil,
        'display_name' => 'system.cpu.idle'
    }],
    'from_date' => 1430309983000,
    'group_by' => ['host'],
    'to_date' => 1430313583000,
    'query' => 'system.cpu.idle{*}by{host}',
    'message' => ''
}
{
  "status": "ok",
  "res_type": "time_series",
  "series": [
    {
      "metric": "system.cpu.idle",
      "attributes": {},
      "display_name": "system.cpu.idle",
      "unit": null,
      "pointlist": [
        [
          1430311800000,
          98.19375610351562
        ],
        [
          1430312400000,
          99.85856628417969
        ]
      ],
      "end": 1430312999000,
      "interval": 600,
      "start": 1430311800000,
      "length": 2,
      "aggr": null,
      "scope": "host:vagrant-ubuntu-trusty-64",
      "expression": "system.cpu.idle{host:vagrant-ubuntu-trusty-64}"
    }
  ],
  "from_date": 1430226140000,
  "group_by": [
    "host"
  ],
  "to_date": 1430312540000,
  "query": "system.cpu.idle{*}by{host}",
  "message": ""
}

View metric metadata

The metrics metadata endpoint allows you to get metadata about a specific metric.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/metrics/<METRIC_NAME>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

metric = 'system.cpu.idle'

api.Metadata.get(metric_name=metric)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Get metadata on metric
result = dog.get_metadata('system.net.bytes_sent')

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

metric_name="system.net.bytes_sent"

curl "https://api.datadoghq.com/api/v1/metrics/${metric_name}?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    'description': 'Percent of time the CPU spent in an idle state.',
    'short_name': 'cpu idle',
    'integration': 'system',
    'statsd_interval': None,
    'per_unit': None,
    'type': 'gauge',
    'unit': 'percent'
}
{
 	"description" => "Percent of time the CPU spent in an idle state.",
 	"short_name" => "cpu idle",
 	"integration" => "system",
 	"statsd_interval" => nil,
 	"per_unit" => nil,
 	"type" => "gauge",
 	"unit" => "percent"
}
{
  "description": "My custom description",
  "short_name":"bytes sent",
  "integration": null,
  "statsd_interval": null,
  "per_unit": "second",
  "type": "gauge",
  "unit": "byte"
}

Edit metric metadata

The metrics metadata endpoint allows you to edit fields of a metric’s metadata. Find more about supported types

ARGUMENTS
  • type [required]: Metric type such as gauge or rate
  • description [optional, default=None]: String description of the metric” default
  • short_name [required]: Short name string of the metric
  • unit [optional, default=None]: Primary unit of the metric such as byte or operation
  • per_unit [optional, default=None]: Per unit of the metric such as second in bytes per second
  • statsd_interval [optional, default=None]: If applicable, statds flush interval in seconds for the metric
Signature

PUT /v1/metrics/<METRIC_NAME>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

metric = 'system.net.bytes_sent'
params = {
    'description': 'My custom description',
    'short_name': 'bytes sent',
    'type': 'gauge',
    'unit': 'byte',
    'per_unit': 'second'
}

api.Metadata.update(metric_name=metric, **params)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

updates = {
    "type" => "gauge",
    "description" => "my custom description",
    "short_name" => "bytes sent",
    "unit" => "byte",
    "per_unit" => "second"
}

# Submit updates for metric
result = dog.update_metadata('system.net.bytes_sent', updates)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

metric_name="system.net.bytes_sent"

curl -X PUT -H "Content-type: application/json" \
-d '{
      "type": "gauge",
      "description": "my custom description",
      "short_name": "bytes sent",
      "unit": "byte",
      "per_unit": "second"
}' \
    "https://api.datadoghq.com/api/v1/metrics/${metric_name}?api_key=${api_key}&application_key=${app_key}"

Example Response
{
    'description': 'My custom description',
    'short_name': 'bytes sent',
    'integration': None,
    'statsd_interval': None,
    'per_unit': 'second',
    'type': 'gauge',
    'unit': 'byte'
}
{
 	"description" => "My custom description",
 	"short_name" => "bytes sent",
 	"integration" => nil,
 	"statsd_interval" => nil,
 	"per_unit" => "second",
 	"type" => "gauge",
 	"unit" => "byte"
}
{
  "description": "my custom description",
  "short_name": "bytes sent",
  "integration": null,
  "statsd_interval": null,
  "per_unit": "second",
  "type": "gauge",
  "unit": "byte"
}

Search metrics

This endpoint allows you to search for metrics from the last 24 hours in Datadog.

ARGUMENTS
  • q [required]: The query string. Must be prefixed with metrics:.
Signature

GET /v1/search

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.Hosts.search(q="metrics:system")
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dog.search("metrics:system")
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -G "https://api.datadoghq.com/api/v1/search" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "q=metrics:test"

Example Response

{
    'results': {
        'metrics': [
            'test.metric.metric',
            'test.tag.metric'
        ]
    }
}
["200", {
    "results" => {
        "metrics" => ["test.metric"]
    }
}]
{
  "results": {
    "metrics": [
      "test.metric"
    ]
  }
}

Monitors

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

Create a monitor

If you manage and deploy monitors programmatically, it’s easier to define the monitor in the Datadog UI and export its valid JSON.

ARGUMENTS
Monitor Typetype attribute value
anomalyquery alert
apmquery alert
compositecomposite
customservice check
eventevent alert
forecastquery alert
hostservice check
integrationquery alert or service check
live processprocess alert
logslog alert
metricmetric alert
networkservice check
outlierquery alert
processservice check
watchdogevent alert
  • query [required]: The query defines when the monitor triggers. Query syntax depends on what type of monitor you are creating:

    Metric Alert Query

    time_aggr(time_window):space_aggr:metric{tags} [by {key}] operator #

    • time_aggr: avg, sum, max, min, change, or pct_change
    • time_window: last_#m (with # being 5, 10, 15, or 30) or last_#h(with # being 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

    If you are using the _change_ or _pct_change_ time aggregator, instead use change_aggr(time_aggr(time_window), timeshift):space_aggr:metric{tags} [by {key}] operator # with:

    • change_aggr change, pct_change
    • time_aggr avg, sum, max, min Learn more
    • time_window last#m (1, 5, 10, 15, or 30), last#h (1, 2, or 4), or last_#d (1 or 2)
    • timeshift #m_ago (5, 10, 15, or 30), #h_ago (1, 2, or 4), or 1d_ago

    Use this to create an outlier monitor using the following query: avg(last_30m):outliers(avg:system.cpu.user{role:es-events-data} by {host}, 'dbscan', 7) > 0

    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. It is limited to 10.
    Event Alert Query

    events('sources:nagios status:error,warning priority:normal tags: "string query"').rollup("count").last("1h")"

    • event, the event query string:
    • string_query free text query to match against event title and text.
    • sources event sources (comma-separated). Complete list of source attribute values
    • status event statuses (comma-separated). Valid options: error, warn, and info.
    • priority event priorities (comma-separated). Valid options: low, normal, all.
    • host event reporting host (comma-separated).
    • tags event tags (comma-separated).
    • excluded_tags exluded event tags (comma-separated).
    • rollup the stats rollup method. count is the only supported method now.
    • last the timeframe to roll up the counts. Examples: 60s, 4h. Supported timeframes: s, m, h and d.
    Process Alert Query

    processes(search).over(tags).rollup('count').last(timeframe) operator #

    • search free text search string for querying processes. Matching processes match results on the Live Processes page
    • tags one or more tags (comma-separated)
    • timeframe the timeframe to roll up the counts. Examples: 60s, 4h. Supported timeframes: s, m, h and d
    • operator <, <=, >, >=, ==, or !=
    • # an integer or decimal number used to set the threshold
    Composite Query

    12345 && 67890, where 12345 and 67890 are the IDs of non-composite monitors

  • name [required, default = dynamic, based on query]: The name of the alert.

  • message [required, 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.

  • tags [optional, default = empty list]: A list of tags to associate with your monitor. When getting all monitor details via the API, use the monitor_tags argument to filter results by these tags. It is only available via the API and isn’t visible or editable in the Datadog UI.

  • options [optional, default={}]: 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 is 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}
    • new_host_delay Time (in seconds) to allow a host to boot and applications to fully start before starting the evaluation of monitor results. Should be a non negative integer. Default: 300

    • notify_no_data a Boolean indicating whether this monitor notifies when data stops reporting. Default: false

    • no_data_timeframe the number of minutes before a monitor notifies when data stops reporting. This parameter is mandatory when notify_no_data​ is set to true. It 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 automatically resolves from a triggered state. Default: None.

    • require_full_window a Boolean indicating whether this monitor needs a full window of data before it’s evaluated. We highly recommend you set this to False for sparse metrics, otherwise some evaluations are skipped. Default: True for “on average”, “at all times” and “in total” aggregation. False otherwise.

    • renotify_interval the number of minutes after the last notification before a monitor re-notifies on the current status. It only re-notifies 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 is notified on changes to this monitor. Default: False

    • locked a Boolean indicating whether changes to to this monitor should be restricted to the creator or admins. Default: False

    • include_tags a Boolean indicating whether notifications from this monitor automatically inserts its triggering tags into the title. Default: True Examples:

      • True: [Triggered on {host:h1}] Monitor Title
      • False: [Triggered] Monitor Title
    Anomaly Options

    These options only apply to anomaly monitors and are ignored for other monitor types.

    • threshold_windows a dictionary containing recovery_window and trigger_window.

      • recovery_window describes how long an anomalous metric must be normal before the alert recovers
      • trigger_window describes how long a metric must be anomalous before an alert triggers

        Example: {'threshold_windows': {'recovery_window': 'last_15m', 'trigger_window': 'last_15m'}}

    Metric Alert Options

    These options only apply to metric alerts.

    • thresholds a dictionary of thresholds by threshold type. There are two threshold types for metric alerts: critical and warning. Critical is defined in the query, but can also be specified in this option. Warning threshold can only be specified using the thresholds option. If you want to use recovery thresholds for your monitor, use the attributes critical_recovery and warning_recovery.

      Example: `{'critical': 90, 'warning': 80,  'critical_recovery': 70, 'warning_recovery': 50}`
      
    • evaluation_delay Time (in seconds) to delay evaluation, as a non-negative integer. For example, if the value is set to 300 (5min), the timeframe is set to last_5m and the time is 7:00, the monitor evaluates data from 6:50 to 6:55. This is useful for AWS CloudWatch and other backfilled metrics to ensure the monitor always has data during evaluation.

    Service Check Options

    These options only apply to service checks and are 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.

      Example: `{'ok': 1, 'critical': 1, 'warning': 1}`
      
    Errors and Validation

    If an invalid monitor option is included in the request, the response will be:

        Error: 400 - ["Invalid monitor option:<invalid option>"]
    
Signature

POST /v1/monitor

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Create a new monitor
monitor_options = {
    "notify_no_data": True,
    "no_data_timeframe": 20
}
tags = ["app:webserver", "frontend"]
api.Monitor.create(
    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.",
    tags=tags,
    options=monitor_options
)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Create a new monitor
options = {
    'notify_no_data' => true,
    'no_data_timeframe' => 20
}
tags = ['app:webserver', 'frontend']
dog.monitor("metric alert", "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.", :tags => tags, :options => options)
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

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.",
      "tags": ["app:webserver", "frontend"],
      "options": {
      	"notify_no_data": true,
      	"no_data_timeframe": 20
      }
}' \
    "https://api.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',
 'tags': ['app:webserver', 'frontend'],
 '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',
 'multi': False,
 'created': '2015-12-18T16:34:14.014039+00:00',
 'modified': '2015-12-18T16:34:14.014039+00:00'
 }
["200", {
    "name" => "Bytes received on host0",
    "org_id" => 1499,
    "tags" => ["app:webserver", "frontend"],
    "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,
    "multi" => false,
    "created" => "2015-12-18T16:34:14.014039+00:00",
    "modified" => "2015-12-18T16:34:14.014039+00:00"
}]
{
  "id": 92090,
  "message": "We may need to add web hosts if this is consistently high.",
  "name": "Bytes received on host0",
  "tags": ["app:webserver", "frontend"],
  "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",
  "multi": false,
  "created": "2015-12-18T16:34:14.014039+00:00",
  "modified": "2015-12-18T16:34:14.014039+00:00"
}

Get a monitor’s details

ARGUMENTS
  • group_states [optional, default=None]: If this argument is set, the returned data includes additional information (if available) regarding the specified group states, including the last notification timestamp, last resolution timestamp and details about the last time the monitor was triggered. The argument should include a string list indicating what, if any, group states to include. Choose one or more from all, alert, warn, or no data. Example: ‘alert,warn’”
Signature

GET /v1/monitor/<MONITOR_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Get a monitor's details
api.Monitor.get(2081, group_states='all')
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Get a monitors's details
dog.get_monitor(91879, :group_states => 'all')
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
monitor_id=<YOUR_MONITOR_ID>

# Show a monitor
curl -G "https://api.datadoghq.com/api/v1/monitor/${monitor_id}" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}" \
     -d "group_states=all"
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',
    'multi': False,
    'created': '2015-12-18T16:34:14.014039+00:00',
    'modified': '2015-12-18T16:34:14.014039+00:00',
    "state": {
        "groups": {
            "host:host0": {
                "last_nodata_ts": null,
                "last_notified_ts": 1481909160,
                "last_resolved_ts": 1481908200,
                "last_triggered_ts": 1481909160,
                "name": "host:host0",
                "status": "Alert",
                "triggering_value": {
                    "from_ts": 1481909037,
                    "to_ts": 1481909097,
                    "value": 1000
                }
            }
        }
    }
}
["200", {
    "name" => "Bytes received on host0",
    "org_id" => 1499,
    "options" => {
        "no_data_timeframe" => 20,
        "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,
    "multi" => false,
    "created" => "2015-12-18T16:34:14.014039+00:00",
    "modified" => "2015-12-18T16:34:14.014039+00:00",
    "state" => {
        "groups" => {
            "host:host0" => {
                "last_nodata_ts" => null,
                "last_notified_ts" => 1481909160,
                "last_resolved_ts" => 1481908200,
                "last_triggered_ts" => 1481909160,
                "name" => "host:host0",
                "status" => "Alert",
                "triggering_value" => {
                    "from_ts" => 1481909037,
                    "to_ts" => 1481909097,
                    "value" => 1000
                }
            }
        }
    }
}]

{
  "id": 91879,
  "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": false,
    "silenced": {}
  },
  "org_id": 1499,
  "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
  "type": "metric alert",
  "multi": false,
  "created": "2015-12-18T16:34:14.014039+00:00",
  "modified": "2015-12-18T16:34:14.014039+00:00",
  "state": {
    "groups": {
      "host:host0": {
        "last_nodata_ts": null,
        "last_notified_ts": 1481909160,
        "last_resolved_ts": 1481908200,
        "last_triggered_ts": 1481909160,
        "name": "host:host0",
        "status": "Alert",
        "triggering_value": {
          "from_ts": 1481909037,
          "to_ts": 1481909097,
          "value": 1000
        }
      }
    }
  }
}

Edit A Monitor

ARGUMENTS
  • query [required]: The metric query to alert on.
  • name [required]: 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={}]: Refer to the create monitor documentation for details on the available options.
  • tags [optional, default=None]: A list of tags to associate with your monitor. This can help you categorize and filter monitors
Signature

PUT /v1/monitor/<MONITOR_ID>

Example Request
from datadog import initialize,  api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Edit an existing monitor
api.Monitor.update(
    2081,
    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."
)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Edit an existing monitor
dog.update_monitor(91879, "avg(last_5m):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.")
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
monitor_id=<YOUR_MONITOR_ID>

# Edit a monitor
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://api.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',
    'multi': False,
    'created': '2015-12-18T16:34:14.014039+00:00',
    'modified': '2015-12-18T18:39:24.391207+00:00'
}
[
    "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,
        "multi" => false,
        "created" => "2015-12-18T16:34:14.014039+00:00",
        "modified" => "2015-12-18T18:39:24.391207+00:00"
    }
]
{   "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",
  "multi": false,
  "created": "2015-12-18T16:34:14.014039+00:00",
"modified": "2015-12-18T18:39:24.391207+00:00"}

Delete a monitor

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

DELETE /v1/monitor/<MONITOR_ID>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Delete a monitor
api.Monitor.delete(2081)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Delete a monitor
dog.delete_monitor(62625)
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
monitor_id=<YOUR_MONITOR_ID>

# Delete a monitor
curl -X DELETE "https://api.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]: If this argument is set, the returned data includes additional information (if available) regarding the specified group states, including the last notification timestamp, last resolution timestamp and details about the last time the monitor was triggered. The argument should include a string list indicating what, if any, group states to include. Choose one or more from ‘all’, ‘alert’, ‘warn’, or ‘no data’. Example: ‘alert,warn’
  • name [optional, default=None]: A string to filter monitors by name
  • tags [optional, default=None]: A comma separated list indicating what tags, if any, should be used to filter the list of monitorsby scope, e.g. host:host0. For more information, see the tags parameter for the appropriate query argument in the Create a monitor section above.
  • monitor_tags [optional, default=None]: A comma separated list indicating what service and/or custom tags, if any, should be used to filter the list of monitors. Tags created in the Datadog UI automatically have the service key prepended (e.g. service:my-app)
  • with_downtimes [optional, default = true]: If this argument is set to true, then the returned data includes all current downtimes for each monitor.
  • page [optional, default = 0]: The page to start paginating from. If this argument is not specified, the request returns all monitors without pagination.
  • page_size [optional, default=100]: The number of monitors to return per page. If the page argument is not specified, the default behavior returns all monitors without a page_size limit. However, if page is specified and page_size is not, the argument defaults to 100.
Signature

GET /v1/monitor

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Get all monitor details
print api.Monitor.get_all()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Get all monitor details
dog.get_all_monitors()
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -G "https://api.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,
        'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
        'type': 'metric alert',
        'multi': False,
        'created': '2015-12-18T16:34:14.014039+00:00',
        'modified': '2015-12-18T18:39:24.391207+00:00'},
    {'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',
     'multi': False,
     'created': '2015-12-18T16:34:14.014039+00:00',
     'modified': '2015-12-18T18:39:24.391207+00:00'
     }
]
[
    "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",
        "multi" => false,
        "id" => 91879,
        "created" => "2015-12-18T16:34:14.014039+00:00",
        "modified" => "2015-12-18T16:34:14.014039+00:00"
    }, {
        "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",
        "multi" => false,
        "id" => 91875,
        "created" => "2015-12-18T16:34:14.014039+00:00",
        "modified" => "2015-12-18T16:34:14.014039+00:00"
    }]
]
[  
   {  
      "tags":[  

      ],
      "deleted":null,
      "query":"change(avg(last_5m),last_1m):avg:apache.net.hits{*} by {host} > 500",
      "message":"Host {{host.name}} with IP {{host.ip}} is under heavy load.",
      "matching_downtimes":[  

      ],
      "id":1111111,
      "multi":true,
      "name":"example title",
      "created":"2019-03-11T17:20:45.414125+00:00",
      "created_at":1552324845000,
      "creator":{  
         "id":1111111,
         "handle":"example@example.com",
         "name":"Jane Doe",
         "email":"example@example.com"
      },
      "org_id":1111111,
      "modified":"2019-03-11T17:20:45.414125+00:00",
      "overall_state_modified":"2019-03-19T12:55:48.320241+00:00",
      "overall_state":"No Data",
      "type":"query alert",
      "options":{  
         "notify_audit":false,
         "locked":false,
         "timeout_h":0,
         "silenced":{  

         },
         "include_tags":true,
         "no_data_timeframe":null,
         "require_full_window":true,
         "new_host_delay":300,
         "notify_no_data":false,
         "renotify_interval":0,
         "escalation_message":"",
         "thresholds":{  
            "critical":500,
            "warning":250
         }
      }
   },
   {  
      "tags":[  

      ],
      "deleted":null,
      "query":"avg(last_1m):outliers(avg:apache.net.hits{*} by {host}, 'DBSCAN', 3) > 0",
      "message":"@example@example.com",
      "matching_downtimes":[  

      ],
      "id":1111111,
      "multi":true,
      "name":"example title",
      "created":"2019-03-11T18:10:09.957865+00:00",
      "created_at":1552327809000,
      "creator":{  
         "id":111111,
         "handle":"example@example.com",
         "name":"Jane Doe",
         "email":"example@example.com"
      },
      "org_id":1111111,
      "modified":"2019-03-11T18:11:25.217705+00:00",
      "overall_state_modified":"2019-03-20T12:50:45.684420+00:00",
      "overall_state":"No Data",
      "type":"query alert",
      "options":{  
         "notify_audit":false,
         "locked":false,
         "timeout_h":0,
         "silenced":{  

         },
         "include_tags":true,
         "no_data_timeframe":null,
         "require_full_window":true,
         "new_host_delay":300,
         "notify_no_data":false,
         "renotify_interval":0,
         "escalation_message":""
      }
   }
]

Resolve monitor

ARGUMENTS
  • resolve [required]: Array of group(s) to resolve for a given monitor_id, e.g.: {"monitor_id": "group_to_resolve"}

    It supports multiple groups per monitor, e.g.: resolve: [{"monitor_id": "group_1"}, {"monitor_id": "group_2"}]

    It can also resolve all triggered groups with the pseudo-group ALL_GROUPS: resolve: [{"monitor_id": "ALL_GROUPS"}]

Signature

POST https://api.datadoghq.com/monitor/bulk_resolve

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>


curl -X POST -H "Content-type: application/json" \
-d '{
"resolve": [
          {"<YOUR_MONITOR_ID>": "<YOUR_FIRST_GROUP>"},
          {"<YOUR_MONITOR_ID>": "<YOUR_SECOND_GROUP>"}
      ]
}' \
    "https://app.datadoghq.com/monitor/bulk_resolve?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
[
  {
    "tags": [
      "*"
    ],
    "deleted": null,
    "query": "avg(last_1h):avg:system.cpu.user{role:cassandra} by {host} > 10",
    "message": "I'm a dummy test.",
    "id": 2610751,
    "multi": true,
    "name": "[Do not mind] This is a test",
    "created": "2017-08-09T14:30:38.584147+00:00",
    "created_at": 1502289038000,
    "org_id": 11287,
    "modified": "2017-08-09T14:36:48.176919+00:00",
    "overall_state_modified": "2017-08-11T12:21:05.949182+00:00",
    "overall_state": "Alert",
    "type": "metric alert",
    "options": {
      "notify_audit": false,
      "locked": false,
      "timeout_h": 0,
      "silenced": {},
      "include_tags": false,
      "no_data_timeframe": 10,
      "new_host_delay": 300,
      "require_full_window": false,
      "notify_no_data": false,
      "renotify_interval": 0,
      "escalation_message": "",
      "thresholds": {
        "critical": 10,
        "warning": 5
      }
    }
  }
]

Mute all monitors

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

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

POST /v1/monitor/mute_all

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

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

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Mute all alerts
dog.mute_monitors()
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" "https://api.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

Disables muting all monitors. Throws an error if mute all was not enabled previously.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

POST /v1/monitor/unmute_all

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

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

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Unmute all alerts
dog.unmute_monitors()
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" "https://api.datadoghq.com/api/v1/monitor/unmute_all?api_key=${api_key}&application_key=${app_key}"
Example Response

This endpoint 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. For example, if your alert is grouped by {host}, you might mute host:app1.
  • end [optional, default=None]: A POSIX timestamp for when the mute should end.
Signature

POST /v1/monitor/<MONITOR_ID>/mute

Example Request

from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Mute a monitor
api.Monitor.mute(2088)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Mute a monitor
dog.mute_monitor(62628)
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
monitor_id=<YOUR_MONITOR_ID>

# Mute a monitor
curl -X POST -H "Content-type: application/json" "https://api.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',
    'created': '2015-12-18T16:34:14.014039+00:00',
    'modified': '2015-12-18T18:39:24.391207+00:00'
}
[
    "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,
        "created" => "2015-12-18T16:34:14.014039+00:00",
        "modified" => "2015-12-18T18:39:24.391207+00:00"
    }
]
{
  "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",
  "created": "2015-12-18T16:34:14.014039+00:00",
  "modified": "2015-12-18T18:39:24.391207+00:00"
}

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’
  • all_scopes [optional, default = False]: Clear muting across all scopes
Signature

POST /v1/monitor/<MONITOR_ID>/unmute

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Unmute all alerts
api.Monitor.unmute(2088)
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Unmute all alerts
dog.unmute_monitor(62628)
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
monitor_id=<YOUR_MONITOR_ID>

# Unmute a monitor
curl -X POST "https://api.datadoghq.com/api/v1/monitor/${monitor_id}/unmute?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',
    'created': '2015-12-18T16:34:14.014039+00:00',
    'modified': '2015-12-18T18:39:24.391207+00:00'
}
[
    "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,
        "created" => "2015-12-18T16:34:14.014039+00:00",
        "modified" => "2015-12-18T18:39:24.391207+00:00"
    }
]
{
  "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",
  "created": "2015-12-18T16:34:14.014039+00:00",
  "modified": "2015-12-18T18:39:24.391207+00:00"
}

Validate a monitor

This endpoint is not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Validates a monitor definition (see Create a monitor for details on constructing a monitor definition).

Signature

POST /v1/monitor/validate

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
      "type": "metric alert",
      "query": "THIS QUERY IS INVALID",
      "name": "Bytes received on host0",
      "message": "We may need to add web hosts if this is consistently high.",
      "tags": ["app:webserver", "frontend"],
      "options": {
      	"notify_no_data": true,
      	"no_data_timeframe": 20
      }
}' \
    "https://api.datadoghq.com/api/v1/monitor/validate?api_key=${api_key}&application_key=${app_key}"
Example Response
{}
["200", {}]
{
    "errors": [
        "The value provided for parameter 'query' is invalid"
    ]
}

Search and filter your monitors details.

ARGUMENTS
  • query [optional]:

    After entering a search query in your Manage Monitor page use the query parameter value in the URL of the page as value for this parameter. Consult the dedicated manage monitor documentation page to learn more.

    The query can contain any number of space-separated monitor attributes, for instance query="type:metric status:alert".

  • page [optional, default = 0]:

    Page to start paginating from.

  • per_page [optional, default=30]:

    Number of monitors to return per page.

  • sort [optional, default=null]:

    Comma separated string for sort order (e.g. name,asc) supported fields:

    • name
    • status
    • tags
Signature

GET /v1/monitor/search

Example Request
from datadog import initialize, api

options = {
	'api_key': '<YOUR_API_KEY>',
	'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Search monitors
api.Monitor.search()

# Examples of possible query parameters:
# api.Monitor.search(query="id:7100311")
# api.Monitor.search(query="title:foo metric:system.core.idle status:Alert")
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Search monitors
dog.search_monitors()

# Examples of possible query parameters:
# dog.search_monitors(query="id:7100311")
# dog.search_monitors(query="title:foo metric:system.core.idle status:Alert")

#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

query=<MANAGE_MONITOR_QUERY>
page=<PAGE_NUMBER>
per_page=<PER_PAGE>
sort=<SORT>

curl -X GET \
    "https://api.datadoghq.com/api/v1/monitor/search?api_key=${api_key}&application_key=${app_key}&query=${query}&page=${page}&per_page=${per_page}&sort=${sort}"
Example Response
{ u'counts': 
    { u'muted': [{ u'count': 1, u'name': False}],
      u'status': [{ u'count': 1, u'name': u'Alert'}],
      u'tag': [ { u'count': 1, u'name': u'env:myenv'},
                { u'count': 1, u'name': u'service:sample'}],
      u'type': [{ u'count': 1, u'name': u'apm'}]},
  u'metadata': { u'page': 0,
                 u'page_count': 1,
                 u'per_page': 30,
                 u'total_count': 1},
  u'monitors': 
    [ { u'classification': u'apm',
        u'creator': { u'handle': u'jane@example.com',
                      u'id': 795042,
                      u'name': u'Jane'},
        u'id': 6797333,
        u'last_triggered_ts': 1540483133,
        u'metrics': [ u'trace.servlet.request.hits',
                      u'trace.servlet.request.errors'],
        u'name': u'Service sample has a high error rate on env:myenv',
        u'notifications': [ { u'handle': u'jane@example.com',
                              u'name': u'Jane'}],
        u'org_id': 11287,
        u'scopes': [u'env:myenv', u'service:sample'],
        u'status': u'Alert',
        u'tags': [u'env:myenv', u'service:sample'],
        u'type': u'query alert'}]}
["200",
 {"counts"=>
   {"status"=>[{"count"=>1, "name"=>"Alert"}],
    "muted"=>[{"count"=>1, "name"=>false}],
    "tag"=>
     [{"count"=>1, "name"=>"env:myenv"},
      {"count"=>1, "name"=>"service:sample"}],
    "type"=>[{"count"=>1, "name"=>"apm"}]},
  "monitors"=>
   [{"status"=>"Alert",
     "scopes"=>["env:myenv", "service:sample"],
     "classification"=>"apm",
     "creator"=>
      {"handle"=>"jane@example.com",
       "id"=>795042,
       "name"=>"Jane"},
     "metrics"=>["trace.servlet.request.hits", "trace.servlet.request.errors"],
     "notifications"=>
      [{"handle"=>"jane@example.com", "name"=>"Jane"}],
     "last_triggered_ts"=>1540483133,
     "id"=>6797333,
     "name"=>"Service sample has a high error rate on env:myenv",
     "tags"=>["env:myenv", "service:sample"],
     "org_id"=>11287,
     "type"=>"query alert"}],
  "metadata"=>{"total_count"=>1, "page_count"=>1, "page"=>0, "per_page"=>30}}]
{
  "counts": {
    "status": [
      {
        "count": 4,
        "name": "No Data"
      },
      {
        "count": 2,
        "name": "OK"
      }
    ],
    "muted": [
      {
        "count": 3,
        "name": false
      },
      {
        "count": 3,
        "name": true
      }
    ],
    "tag": [
      {
        "count": 6,
        "name": "service:cassandra"
      }
    ],
    "type": [
      {
        "count": 6,
        "name": "metric"
      }
    ]
  },
  "monitors": [
    {
      "status": "No Data",
      "scopes": [
        "!availability-zone:us-east-1c",
        "name:cassandra"
      ],
      "classification": "metric",
      "creator": {
        "handle": "xxxx@datadoghq.com",
        "name": "xxxx@datadoghq.com",
        "id": {
          "handle": "xxxx@datadoghq.com",
          "id": 1234,
          "name": null
        }
      },
      "metrics": [
        "system.cpu.user"
      ],
      "notifications": [
        {
          "handle": "xxxx@datadoghq.com",
          "name": "xxxx@datadoghq.com"
        }
      ],
      "last_triggered_ts": null,
      "id": 2699850,
      "name": "Cassandra CPU is high on {{host.name}} in {{availability-zone.name}}",
      "tags": [
        "service:cassandra"
      ],
      "org_id": 1234,
      "type": "metric alert"
    },
    {
      "status": "OK",
      (...)
    },
  ],
  "metadata": {
    "total_count": 6,
    "page_count": 6,
    "page": 0,
    "per_page": 30
  }
}

Search and filter your monitor groups details.

ARGUMENTS
  • query [optional]:

    After entering a search query in your Manage Monitor page use the query parameter value in the URL of the page as value for this parameter. Consult the dedicated manage monitor documentation page to learn more.

  • page [optional, default = 0]:

    Page to start paginating from.

  • per_page [optional, default=30]:

    Number of monitors to return per page.

  • sort [optional, default=null]:

    Comma separated string for sort order (e.g. name,asc) supported fields:

    • name
    • status
    • tags
Signature

GET /v1/monitor/groups/search

Example Request
from datadog import initialize, api

options = {
	'api_key': '<YOUR_API_KEY>',
	'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Search monitor groups
api.Monitor.search_groups()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

# Search monitor groups
dog.search_monitor_groups()
#!/bin/sh
# Replace the API and APP keys below
# with the ones for your account

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

query=<MANAGE_MONITOR_QUERY>
page=<PAGE_NUMBER>
per_page=<PER_PAGE>
sort=<SORT>

curl -X GET \
    "https://api.datadoghq.com/api/v1/monitor/groups/search?api_key=${api_key}&application_key=${app_key}&query=${query}&page=${page}&per_page=${per_page}&sort=${sort}"
Example Response
{ u'counts': 
  { u'status': [{ u'count': 1, u'name': u'Alert'}],
    u'type': [{ u'count': 1, u'name': u'apm'}]},
  u'groups': [ { u'group': u'*',
                 u'group_tags': [u'*'],
                 u'last_nodata_ts': 0,
                 u'last_triggered_ts': 1540483133,
                 u'monitor_id': 6797333,
                 u'monitor_name': u'Service sample has a high error rate on env:myenv',
                 u'status': u'Alert'}],
  u'metadata': { u'page': 0,
                 u'page_count': 1,
                 u'per_page': 30,
                 u'total_count': 1}}
["200",
 {"counts"=>
   {"status"=>[{"count"=>1, "name"=>"Alert"}],
    "type"=>[{"count"=>1, "name"=>"apm"}]},
  "groups"=>
   [{"status"=>"Alert",
     "last_triggered_ts"=>1540483133,
     "group"=>"*",
     "monitor_id"=>6797333,
     "group_tags"=>["*"],
     "last_nodata_ts"=>0,
     "monitor_name"=>"Service sample has a high error rate on env:myenv"}],
  "metadata"=>{"total_count"=>1, "page_count"=>1, "page"=>0, "per_page"=>30}}]
{
  "counts": {
    "status": [
      {
        "count": 2,
        "name": "OK"
      }
    ],
    "type": [
      {
        "count": 2,
        "name": "metric"
      }
    ]
  },
  "groups": [
    {
      "status": "OK",
      "last_triggered_ts": 1525702966,
      "group": "*",
      "monitor_id": 2738266,
      "group_tags": [
        "*"
      ],
      "last_nodata_ts": 0,
      "monitor_name": "[demo] Cassandra disk usage is high on {{host.name}}"
    },
    {
      "status": "OK",
      "last_triggered_ts": 1525703008,
      "group": "*",
      "monitor_id": 1576648,
      "group_tags": [
        "*"
      ],
      "last_nodata_ts": 0,
      "monitor_name": "[demo] Disk usage is high on {{host.name}}"
    }
  ],
  "metadata": {
    "total_count": 2,
    "page_count": 2,
    "page": 0,
    "per_page": 30
  }
}

Organizations

The Organization endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

You can create, edit, and manage organizations. Read more about multi-org accounts.

Create child-organization

This endpoint requires the multi-org account feature and must be enabled by contacting support.

ARGUMENTS
  • name [required]: The name of the new child-organization, limited to 32 characters.
  • subscription [required]: A JSON array of subscription type. Types available are trial, free, and pro.
  • billing [required]: A JSON array of billing type. Note that only parent_billing is supported.

Once a new child-organization is created, you can interact with it by using the org.public_id, api_key.key, and application_key.hash provided in the response.

Signature

POST /v1/org

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" \
    -d '{
        "name" :"My Org",
        "subscription" :{"type":"pro"},
        "billing" :{"type":"parent_billing"}
}' \
    "https://api.datadoghq.com/api/v1/org?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
  "org" : {
    "name" : "My Org",
    "public_id" : "axd2s",
    "subscription" : {
      "type" : "pro"
    },
    "billing" : {
      "type" : "parent_billing"
    }
  },
  "user" : {
    "name" : "Organization admin",
    "handle" : "test@datadoghq.com",
    ...
  },
  "api_key" : {
    "created_by": "user",
    "key": "6ccdfb88ff1aa63192c326"
    ...
  },
  "application_key": {
    "owner": "Organization admin",
    "hash": "88e5ae6a71f51d1d5a0071a24f",
    ...
  }
}

Get organization

Signature

GET /v1/org

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X GET "https://api.datadoghq.com/api/v1/org?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
  "orgs" : [{
      "name" : "My Org",
      "public_id" : "axd2s",
      "subscription" : {
        "type" : "pro"
      },
      "billing" : {
        "type" : "bill-parent"
    }
  }]
}

Update organization

ARGUMENTS
  • name [optional]: The organization name.
  • settings [optional]: A JSON array of settings. Settings include:
    • saml - Set the boolean property enabled to enable or disable single sign on with SAML. See the SAML documentation for more information about all SAML settings.
    • saml_idp_initiated_login - has one property enabled (boolean).v
    • saml_strict_mode - has one property enabled (boolean).
    • saml_autocreate_users_domains - has two properties: enabled (boolean) and domains which is a list of domains without the @ symbol.
Signature

PUT /v1/org/<PUBLIC_ID>

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=axd2s

curl -X PUT -H "Content-type: application/json" \
    -d '{
        "settings": {
            "saml": {
                "enabled": true
            },
            "saml_strict_mode": {
                "enabled": true
            },
            "saml_idp_initiated_login": {
                "enabled": true
            },
            "saml_autocreate_users_domains": {
                "enabled": true,
                "domains": [
                    "my-org.com",
                    "example.com"
                ]
            }
        }
}' \
    "https://api.datadoghq.com/api/v1/org/${public_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
  "org": {
    "public_id": "axd2s",
    "name": "My Org",
           "billing": {},
    "created": "2016-10-06 21:41:12",
    "settings": {
      "saml_can_be_enabled": true,
      "saml_idp_initiated_login": {
        "enabled": true
      },
      "saml": {
        "enabled": true
      },
      "saml_idp_endpoint": "https://idp.datadoghq.com/idp/profile/SAML2/POST/SSO",
      "saml_autocreate_users_domains": {
        "domains": [
          "my-org.com",
          "example.com"
        ],
        "enabled": true
      },
      "saml_login_url": "https://app.datadoghq.com/account/login/id/c81e728d9",
      "saml_idp_metadata_uploaded": true,
      "saml_strict_mode": {
        "enabled": true
      }
    },
    "subscription": {
      "type": "pro"
    }
  }
}

Upload IdP metadata

There are a couple of options for updating the Identity Provider (IdP) metadata from your SAML IdP.

  • Multipart Form-Data: Post the IdP metadata file using a form post.
  • XML Body: Post the IdP metadata file as the body of the request.

Multipart Form-Data

HEADERS
  • Content-Type: multipart/form-data
ARGUMENTS
  • idp_file [required]: The path to the XML metadata file you wish to upload.

XML Body

HEADERS
  • Content-Type: application/xml
ARGUMENTS

The body must contain the contents of your IdP metadata XML file.

Signature

POST /v1/org/<PUBLIC_ID>/idp_metadata

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=<DD_APP_PUBLIC_ID>

# Upload IdP file using multipart/form-data
curl -X POST -H "Content-Type: multipart/form-data" \
    -F "idp_file=@metadata.xml" \
    "https://api.datadoghq.com/api/v1/org/${public_id}/idp_metadata?api_key=${api_key}&application_key=${app_key}"

# OR

# Upload IdP file using application/xml
curl -X POST -H "Content-Type: application/xml" \
    --data-binary "@metadata.xml" \
    "https://api.datadoghq.com/api/v1/org/${public_id}/idp_metadata?api_key=${api_key}&application_key=${app_key}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
  "message": "IdP metadata successfully uploaded for org Datadog HQ"
}

Screenboards

This endpoint is outdated. Use the new Dashboard endpoint instead.

Synthetics

The Synthetics endpoints are not supported in Datadog’s client libraries. To request this functionality, contact Datadog Support.

Datadog Synthetics uses simulated user requests and browser rendering to help you ensure uptime, identify regional issues, and track your application performance.

You can use Datadog’s API to create Synthetics API tests programmatically. API tests are HTTP requests (GET, POST, PUT, PATCH, DELETE) executed by Datadog to your web properties or application endpoints at configurable periodic intervals from multiple locations around the world. These checks verify that your applications are responding to requests, as well as that they meet any conditions you define—such as response time, HTTP status code, and header or body contents.

For more information about Synthetics, see the Synthetics overview.

Create a test

Create a Synthetics test to initiate and configure the tests you want Datadog to send to your API endpoints or to your browser app. You can configure the endpoints being tested, the number of tests, and where they are coming from. The parameters required are different for API and browser tests and they are marked accordingly—if a parameter is marked as required, it is required for both types of tests. Once you create a test, it shows up in the UI in your Synthetics list

A browser test is treated like a GET API test. This method gives you the ability to create the browser test, but you have to use the UI to record your test.

Arguments
  • assertions - required - This is where you are defining exactly what should happen for a test to be considered passed. Each assertion has a: type, operator, target, and possibly a property.
    • type - required API test - The part of the response that you want to assess. Possible types are header, body, responseTime, and statusCode. When you define a header, you must specify the header parameter key in the property parameter, and the header parameter value with the target parameter. For all other types, use the target to specify the body, the response time, and the error messages. For example, a "type":"statusCode" might have a "target":403.
    • operator - required API test - Defines how to compare the target and the actual value from the response. Valid operators depend on the type of assertions. This is the list of valid operators per type:
typeValid operatorValue type
Status Codeis, is notInteger
Response timelessThanInteger
Headerscontains, does not contain, is, is not, matches, does not matchfor contains/does not contain/is/is not: String for matches/does not match: RegexString
Bodycontains, does not contain, is, is not, matches, does not matchfor contains/does not contain/is/is not: String for matches/does not match: RegexString
  • target - required API test - The expected value for the assertion. For header, valid values are any of the valid values for the header key that you define in property. For statusCode, valid values are valid status codes. For responseTime, valid values are the expected response times.
  • property - optional - When you are setting up a header type, this is required to define the headers parameter key. Valid values are any header keys, like Content-Type or Authorization.
  • request - required API test - An object containing all the necessary information to perform the request to your endpoint.
    • method - required - The method of the API to test. Valid values are GET, POST, PUT, PATCH, and DELETE. Use GET for a browser test.
    • url - required - The endpoint for the API Datadog is testing. For a browser test, the URL for the website Datadog is testing.
    • timeout - optional - When the API request will timeout.
    • headers - optional - Headers in the API request.
    • body - optional - The body for the API request. Accepts text strings (including a JSON as a text string). Specify the type using Content-Type property parameter and the type (like application/json or text/plain in the headers paramater.
  • locations - required - A list of the locations that you want the tests to be sent from. At least one value is required, and you can use all locations. For a list of valid locations, use the GET available locations method. At least one value is required, and you can use all locations.
  • message - required - A description of the test.
  • name - required - A unique name for the test.
  • options - required - Use advanced options to specify custom request headers, authentication credentials, body content, cookies, or to have the test follow redirects. All optional parameters take their default value if you don’t specify a value. Valid values in the request object are:
    • ** tick_every:** - required - How often the test should run (in seconds - current possible values are 60, 300, 900, 1800, 3600, 21600, 43200, 86400, 604800).
    • min_failure_duration - optional - How long the test should be in failure before alerting (integer, number of seconds, max 7200). Default is 0.
    • min_location_failed - optional - The minimum number of locations that must have been in failure at the same time during at least one moment in the min_failure_duration period (min_location_failed and min_failure_duration are part of the advanced alerting rules - integer, >= 1. Default is 1.
    • follow_redirects - optional - boolean - whether to follow redirects or not (max ten redirects can be followed before triggering a “Too many redirects” error). Valid values are true or false. Default value is false.
    • device_ids - required browser test - The type of device you want to use to test. To get a list of available devices, use the GET devices for browser checkes method and use the id from the response. At least one device is required.
  • tags - optional - Tags you want to use to filter your test when you are viewing it in Datadog. For more info on custom tags, see Using tags.
  • type - required - The type of test. Valid values are api and browser.
Signature

POST /v1/synthetics/tests/

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
### To create an API test

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST \
  "https://api.datadoghq.com/api/v1/synthetics/tests?api_key=${api_key}&application_key=${app_key}" \
  -H 'Content-Type: application/json' \
  -d '{
   "config":{
      "assertions":[
         {
            "operator":"is",
            "type":"statusCode",
            "target":403
         },
         {
            "operator":"is",
            "property":"content-type",
            "type":"header",
            "target":"text/html"
         },
         {
            "operator":"lessThan",
            "type":"responseTime",
            "target":2000
         }
      ],
      "request":{
         "method":"GET",
         "url":"https://datadoghq.com",
         "timeout":30,
         "headers":{
            "header1":"value1",
            "header2":"value2"
         },
         "body":"body to send with the request"
      }
   },
   "locations":[
      "aws:us-east-2",
      "aws:eu-central-1",
      "aws:ca-central-1",
      "aws:eu-west-2",
      "aws:ap-northeast-1",
      "aws:us-west-2",
      "aws:ap-southeast-2"
   ],
   "message":"test",
   "name":"Test",
   "options":{
      "tick_every":60,
      "min_failure_duration":0,
      "min_location_failed":1,
      "follow_redirects":true
   },
   "tags":[
      "foo:bar"
   ],
   "type":"api"
}'

### To create a browser test

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl  -X POST -H "Content-type: application/json" \
-d '{
   "locations":[
      "aws:ca-central-1",
      "aws:us-east-2"
   ],
   "options":{
      "device_ids":[
         "laptop_large"
      ],
      "tick_every":3600,
      "min_failure_duration":0,
      "min_location_failed":1
   },
   "name":"Test Doc",
   "config":{
      "assertions":[

      ],
      "request":{
         "method":"GET",
         "url":"https://example.com/"
      }
   },
   "message":"Test message",
   "tags":[

   ],
   "type":"browser"
}' \
"https://api.datadoghq.com/api/v1/synthetics/tests?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "status":"live",
   "public_id":"sti-s2m-ciz",
   "tags":[  
      "foo:bar"
   ],
   "locations":[  
      "aws:us-east-2",
      "aws:eu-central-1",
      "aws:ca-central-1",
      "aws:eu-west-2",
      "aws:ap-northeast-1",
      "aws:us-west-2",
      "aws:ap-southeast-2"
   ],
   "message":"test",
   "deleted_at":null,
   "name":"Test",
   "type":"api",
   "created_at":"2019-04-18T14:35:28.378610+00:00",
   "modified_at":"2019-04-18T14:35:28.378610+00:00",
   "config":{  
      "request":{  
         "url":"https://datadoghq.com",
         "headers":{  
            "header2":"value2",
            "header1":"value1"
         },
         "body":"body to send with the request",
         "method":"GET",
         "timeout":30
      },
      "assertions":[  
         {  
            "operator":"is",
            "type":"statusCode",
            "target":403
         },
         {  
            "operator":"is",
            "property":"content-type",
            "type":"header",
            "target":"text/html"
         },
         {  
            "operator":"lessThan",
            "type":"responseTime",
            "target":2000
         }
      ]
   },
   "options":{  
      "follow_redirects":true,
      "min_failure_duration":0,
      "tick_every":60,
      "min_location_failed":1
   }
}

Start or pause a test

Use this method to start or pause an existing Synthetics test.

Arguments
  • new_status - required - A key-value pair where you define whether you want to start or pause a test. Valid values are live and paused. Returns true if the status has been changed, and false if the status has stayed the same.
Signature

POST /v1/synthetics/tests/<SYNTHETICS_TEST_PUBLIC_ID>/status

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
#!/bin/bash

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=<SYNTHETICS_TEST_PUBLIC_ID>

curl -X PUT -H "Content-type: application/json" \
-d '{"new_status":"paused"}' \
"https://api.datadoghq.com/api/v1/synthetics/tests/${public_id}/status?api_key=${api_key}&application_key=${app_key}"
Example Response
true

Edit a test

Use this method to update an existing Synthetics test. In order to update a test, you have to submit the same payload as creating a test.

The parameters required are different for API and browser tests and they are marked accordingly—if a parameter is marked as required, it is required for both types of tests.

A browser test is treated like a GET API test. This method gives you the ability to update the browser test, but you have to use the UI to record your test.

In order to update a request, you have to submit a full object, but only these parameters are editable: name, tags, config (anything defined in the assertions and anything defined in the request), message, options, locations, and status.

Arguments
  • assertions - required - This is where you are defining exactly what should happen for a test to be considered passed. Each assertion has a: type, operator, target, and possibly a property.
    • type - required API test - The part of the response that you want to assess. Possible types are header, body, responseTime, and statusCode. When you define a header, you must specify the header parameter key in the property parameter, and the header parameter value with the target parameter. For all other types, use the target to specify the body, the response time, and the error messages. For example, a "type":"statusCode" might have a "target":403.
    • operator - required API test - Defines how to compare the target and the actual value from the response. Valid operators depend on the type of assertions. This is the list of valid operators per type:
typeValid operatorValue type
Status Codeis, is notInteger
Response timeless thanInteger
Headerscontains, does not contain, is, is not, matches, does not matchfor contains/does not contain/is/is not: String for matches/does not match: RegexString
Bodycontains, does not contain, is, is not, matches, does not matchfor contains/does not contain/is/is not: String for matches/does not match: RegexString
  • target - required API test - The expected value for the assertion. For header, valid values are any of the valid values for the header key that you define in property. For statusCode, valid values are valid status codes. For responseTime, valid values are the expected response times.
  • property - optional - When you are setting up a header type, this is required to define the headers parameter key. Valid values are any header keys, like Content-Type or Authorization.
  • request - required API test - An object containing all the necessary information to perform the request to your endpoint.
    • method - required - The method of the API to test. Valid values are GET, POST, PUT, PATCH, and DELETE. Use GET for a browser test.
    • url - required - The endpoint for the API Datadog is testing. For a browser test, the URL for the website Datadog is testing.
    • timeout - optional - When the API request will timeout.
    • headers - optional - Headers in the API request.
    • body - optional The body for the API request. Accepts text strings (including a JSON as a text string). Specify the type using Content-Type property parameter and the type (like application/json or text/plain in the headers paramater.
  • locations - required - A list of the locations that you want the tests to be sent from. At least one value is required, and you can use all locations. For a list of valid locations, use the GET available locations method. At least one value is required, and you can use all locations.
  • message - required - A description of the test.
  • name - required - A unique name for the test.
  • options - required - Use advanced options to specify custom request headers, authentication credentials, body content, cookies, or to have the test follow redirects. All optional parameters take their default value if you don’t specify a value. Valid values in the request object are:
    • tick_every: - required - How often the test should run (in seconds - current possible values are 60, 300, 900, 1800, 3600, 21600, 43200, 86400, 604800).
    • min_failure_duration - optional - How long the test should be in failure before alerting (integer, number of seconds, max 7200). Default is 0.
    • min_location_failed - optional - The minimum number of locations that must have been in failure at the same time during at least one moment in the min_failure_duration period (min_location_failed and min_failure_duration are part of the advanced alerting rules - integer, >= 1. Default is 1.
    • follow_redirects - optional - boolean - whether to follow redirects or not (max ten redirects can be followed before triggering a “Too many redirects” error). Valid values are true or false. Default value is false.
    • device_ids - required browser test - The type of device you want to use to test. To get a list of available devices, use the GET devices for browser checkes method and use the id from the response. At least one device is required.
  • tags - optional - Tags you want to use to filter your test when you are viewing it in Datadog. For more info on custom tags, see Using tags.
  • type - required - The type of test. Valid values are api and browser.
Signature

PUT /v1/synthetics/tests/<SYNTHETICS_TEST_PUBLIC_ID>

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
#!/bin/bash

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=<SYNTHETICS_TEST_PUBLIC_ID>

curl -X PUT -H "Content-type: application/json" \
-d '{
   "config":{
      "assertions":[
         {
            "operator":"is",
            "type":"statusCode",
            "target":403
         },
         {
            "operator":"is",
            "property":"content-type",
            "type":"header",
            "target":"text/html"
         },
         {
            "operator":"lessThan",
            "type":"responseTime",
            "target":2000
         }
      ],
      "request":{
         "method":"GET",
         "url":"https://datadoghq.com",
         "timeout":30,
         "headers":{
            "header1":"value1",
            "header2":"value2"
         },
         "body":"body to send with the request"
      }
   },
   "locations":[
      "aws:us-east-2",
      "aws:eu-central-1",
      "aws:ca-central-1",
      "aws:eu-west-2",
      "aws:ap-northeast-1",
      "aws:us-west-2",
      "aws:ap-southeast-2"
   ],
   "message": "test-edited",
   "name":"Test",
   "options":{
      "tick_every":60,
      "min_failure_duration":0,
      "min_location_failed":1,
      "follow_redirects":true
   },
   "tags":[
      "foo:bar"
   ],
   "type":"api"
}' \
"https://api.datadoghq.com/api/v1/synthetics/tests/${public_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "status":"live",
   "public_id":"aaa-bbb-ccc",
   "tags":[  
      "foo:bar"
   ],
   "locations":[  
      "aws:us-east-2",
      "aws:eu-central-1",
      "aws:ca-central-1",
      "aws:eu-west-2",
      "aws:ap-northeast-1",
      "aws:us-west-2",
      "aws:ap-southeast-2"
   ],
   "message":"test-edited",
   "deleted_at":null,
   "name":"Test",
   "type":"api",
   "created_at":"2019-04-12T12:29:34.379537+00:00",
   "modified_at":"2019-04-12T12:29:34.379537+00:00",
   "config":{  
      "request":{  
         "url":"https://datadoghq.com",
         "headers":{  
            "sdf":"fds",
            "Cookie":"qds"
         },
         "body":"fs",
         "method":"GET",
         "timeout":30
      },
      "assertions":[  
         {  
            "operator":"is",
            "type":"statusCode",
            "target":403
         },
         {  
            "operator":"is",
            "property":"content-type",
            "type":"header",
            "target":"text/html"
         },
         {  
            "operator":"lessThan",
            "type":"responseTime",
            "target":2000
         }
      ]
   },
   "options":{  
      "follow_redirects":true,
      "min_failure_duration":0,
      "tick_every":60,
      "min_location_failed":1
   }
}

Delete tests

Use this method to delete one or many tests.

Arguments
  • public_ids - required - A JSON list of the ID or IDs of the tests that you want to delete.
Signature

POST /v1/synthetics/tests/delete

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
#!/bin/bash

api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl -X POST -H "Content-type: application/json" \
-d '{
   "public_ids":[
      "aaa-bbb-ccc",
      "bbb-ccc-ddd"
   ]
}' \
"https://api.datadoghq.com/api/v1/synthetics/tests/delete?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "deleted_tests":[  
      {  
         "public_id":"262647",
         "deleted_at":"2019-04-16T21:20:57+0000"
      },
      {  
         "public_id":"262648",
         "deleted_at":"2019-04-16T21:20:57+0000"
      }
   ]
}

Get the most recent results

Use this method to get the most recent results for a specific test.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/synthetics/tests/<SYNTHETICS_TEST_PUBLIC_ID>/results

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=<SYNTHETICS_TEST_PUBLIC_ID>

curl "https://api.datadoghq.com/api/v1/synthetics/tests/${public_id}/results?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "last_timestamp_fetched":1555073253000,
   "results":[  
      {  
         "status":0,
         "probe_dc":"aws:eu-central-1",
         "result_id":"13240452786084775503",
         "result":{  
            "timings":{  
               "firstByte":563.9,
               "tcp":28.8,
               "ssl":60.4,
               "dns":1.0678250044584274,
               "download":0.1,
               "total":654.3
            }
         },
         "check_time":1555074213964
      }
   ]
}

Get a specific result

Use this method to get a specific result for a specific test.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/synthetics/tests/<SYNTHETICS_TEST_PUBLIC_ID>/results/<RESULT_ID>

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=<SYNTHETICS_TEST_PUBLIC_ID>
result_id=<TEST_RESULT_ID>

curl "https://api.datadoghq.com/api/v1/synthetics/tests/${public_id}/results/${result_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "status":0,
   "check_time":1555074753734,
   "check_version":4,
   "result":{  
      "timings":{  
         "firstByte":717.5,
         "tcp":281.8,
         "ssl":565.2,
         "dns":1.103536993265152,
         "download":0.1,
         "total":1565.7
      },
      "mainDC":"us1.prod",
      "eventType":"finished",
      "httpStatusCode":200,
      "responseSize":26693
   },
   "probe_dc":"aws:ap-northeast-1",
   "result_id":"16334500735347249235",
   "check":{  
      "config":{  
         "request":{  
            "url":"https://datadoghq.com/",
            "method":"GET",
            "timeout":30
         },
         "assertions":[  
            {  
               "operator":"is",
               "type":"statusCode",
               "target":200
            }
         ]
      }
   }
}

Get all tests

Use this method to get a list of all existing tests.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/synthetics/tests

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl "https://api.datadoghq.com/api/v1/synthetics/tests?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "tests":[  
      {  
         "status":"live",
         "public_id":"84r-szk-xpt",
         "tags":[  
            "foo:bar"
         ],
         "locations":[  
            "aws:us-east-2",
            "aws:eu-central-1",
            "aws:ca-central-1",
            "aws:eu-west-2",
            "aws:ap-northeast-1",
            "aws:us-west-2",
            "aws:ap-southeast-2"
         ],
         "message":"test",
         "name":"Test",
         "type":"api",
         "created_at":"2019-04-18T14:31:04.087360+00:00",
         "modified_at":"2019-04-18T14:31:04.087360+00:00",
         "config":{  
            "request":{  
               "url":"https://datadoghq.com",
               "headers":{  
                  "header2":"value2",
                  "header1":"value1"
               },
               "body":"body to send with the request",
               "method":"GET",
               "timeout":30
            },
            "assertions":[  
               {  
                  "operator":"is",
                  "type":"statusCode",
                  "target":403
               },
               {  
                  "operator":"is",
                  "property":"content-type",
                  "type":"header",
                  "target":"text/html"
               },
               {  
                  "operator":"lessThan",
                  "type":"responseTime",
                  "target":2000
               }
            ]
         },
         "options":{  
            "follow_redirects":true,
            "min_failure_duration":0,
            "tick_every":60,
            "min_location_failed":1
         }
      },
      {  
         "status":"paused",
         "public_id":"sti-hyu-ciz",
         "tags":[  
            "foo:bar"
         ],
         "locations":[  
            "aws:us-east-2",
            "aws:eu-central-1",
            "aws:ap-northeast-1",
            "aws:us-west-2",
            "aws:ap-southeast-2"
         ],
         "message":"test-edited",
         "name":"Test",
         "type":"api",
         "created_at":"2019-04-18T14:35:28.378610+00:00",
         "modified_at":"2019-04-18T15:04:56.181518+00:00",
         "config":{  
            "request":{  
               "url":"https://datadoghq.com",
               "headers":{  
                  "header2":"value2",
                  "header1":"value1"
               },
               "body":"body to send with the request",
               "method":"GET",
               "timeout":30
            },
            "assertions":[  
               {  
                  "operator":"is",
                  "type":"statusCode",
                  "target":403
               },
               {  
                  "operator":"is",
                  "property":"content-type",
                  "type":"header",
                  "target":"text/html"
               },
               {  
                  "operator":"lessThan",
                  "type":"responseTime",
                  "target":2000
               }
            ]
         },
         "options":{  
            "follow_redirects":true,
            "min_failure_duration":0,
            "tick_every":60,
            "min_location_failed":1
         }
      },
      {  
         "status":"paused",
         "public_id":"s6z-mno-2g6",
         "tags":[  

         ],
         "locations":[  
            "aws:ca-central-1",
            "aws:us-east-2"
         ],
         "message":"Test message",
         "name":"Test Doc",
         "type":"browser",
         "created_at":"2019-04-18T14:39:38.057734+00:00",
         "modified_at":"2019-04-18T14:39:38.057734+00:00",
         "config":{  
            "request":{  
               "url":"https://docs.datadoghq.com/",
               "method":"GET"
            },
            "assertions":[  

            ]
         },
         "options":{  
            "min_failure_duration":0,
            "device_ids":[  
               "laptop_large"
            ],
            "tick_every":3600,
            "min_location_failed":1
         }
      }
   ]
}

Get a test

Use this method to get information on a specific test.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/synthetics/tests/<SYNTHETICS_TEST_PUBLIC_ID>

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
public_id=<SYNTHETICS_TEST_PUBLIC_ID>

curl "https://api.datadoghq.com/api/v1/synthetics/tests/${public_id}?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "status":"live",
   "public_id":"84r-szk-xpt",
   "tags":[  
      "foo:bar"
   ],
   "locations":[  
      "aws:us-east-2",
      "aws:eu-central-1",
      "aws:ca-central-1",
      "aws:eu-west-2",
      "aws:ap-northeast-1",
      "aws:us-west-2",
      "aws:ap-southeast-2"
   ],
   "message":"test",
   "modified_by":{  
      "email":"example@example.com",
      "handle":"example@example.com",
      "id":1226568,
      "name":"Jane Doe"
   },
   "name":"Test",
   "type":"api",
   "created_at":"2019-04-18T14:31:04.087360+00:00",
   "modified_at":"2019-04-18T14:31:04.087360+00:00",
   "created_by":{  
      "email":"example@example.com",
      "handle":"example@example.com",
      "id":1226568,
      "name":"Jane Doe"
   },
   "overall_state_modified":"2019-04-18T14:31:23.689576+00:00",
   "overall_state":0,
   "config":{  
      "request":{  
         "url":"https://datadoghq.com",
         "headers":{  
            "header2":"value2",
            "header1":"value1"
         },
         "body":"body to send with the request",
         "method":"GET",
         "timeout":30
      },
      "assertions":[  
         {  
            "operator":"is",
            "type":"statusCode",
            "target":403
         },
         {  
            "operator":"is",
            "property":"content-type",
            "type":"header",
            "target":"text/html"
         },
         {  
            "operator":"lessThan",
            "type":"responseTime",
            "target":2000
         }
      ]
   },
   "options":{  
      "follow_redirects":true,
      "min_failure_duration":0,
      "tick_every":60,
      "min_location_failed":1
   }
}

Get devices for browser checks

Get a list of devices for browser checks.

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/synthetics/browser/devices

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl "https://api.datadoghq.com/api/v1/synthetics/browser/devices?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "devices":[  
      {  
         "width":1440,
         "height":1100,
         "id":"laptop_large",
         "isMobile":false,
         "name":"Laptop Large"
      },
      {  
         "width":768,
         "height":1020,
         "id":"tablet",
         "isMobile":true,
         "name":"Tablet"
      },
      {  
         "width":320,
         "height":550,
         "id":"mobile_small",
         "isMobile":true,
         "name":"Mobile Small"
      }
   ]
}


Get available locations

Get a list of available locations

Arguments

This endpoint takes no JSON arguments.

Signature

GET /v1/synthetics/locations

Example Request
# This is not yet supported by the Python Client for the Datadog API
# This is not yet supported by the Ruby Client for the Datadog API
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl "https://api.datadoghq.com/api/v1/synthetics/locations?api_key=${api_key}&application_key=${app_key}"
Example Response
{  
   "locations":[  
      {  
         "is_active":true,
         "region":"Americas",
         "display_name":"Ohio (AWS)",
         "id":30005,
         "name":"aws:us-east-2"
      },
      {  
         "is_active":true,
         "region":"Europe",
         "display_name":"Frankfurt (AWS)",
         "id":3,
         "name":"aws:eu-central-1"
      },
      {  
         "is_active":true,
         "region":"Americas",
         "display_name":"Canada Central (AWS)",
         "id":30003,
         "name":"aws:ca-central-1"
      },
      {  
         "is_active":true,
         "region":"Europe",
         "display_name":"London (AWS)",
         "id":2,
         "name":"aws:eu-west-2"
      },
      {  
         "is_active":true,
         "region":"Asia Pacific",
         "display_name":"Tokyo (AWS)",
         "id":4,
         "name":"aws:ap-northeast-1"
      },
      {  
         "is_active":true,
         "region":"Americas",
         "display_name":"Oregon (AWS)",
         "id":1,
         "name":"aws:us-west-2"
      },
      {  
         "is_active":true,
         "region":"Asia Pacific",
         "display_name":"Sydney (AWS)",
         "id":30004,
         "name":"aws:ap-southeast-2"
      }
   ]
}

Tags

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

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… Complete list of source attribute values

Read more about tags on the dedicated documentation page.

Get tags

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

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

GET /v1/tags/hosts

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

print api.Tag.get_all()
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

dog.all_tags()
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

curl "https://api.datadoghq.com/api/v1/tags/hosts?api_key=${api_key}&application_key=${app_key}"

Example Response


{
    "tags": {
        "role:database",
        "env:test": [
            "test.metric.host"
        ]
    }
}
["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": {
    "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

This endpoint takes no JSON arguments.

Signature

GET /v1/tags/hosts/<HOSTNAME>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Get tags by hostname
hostname='<YOUR_HOSTNAME>'
hosts = api.Hosts.search(q='hosts:')

for host in hosts['host_list']:
    if host['name'] == hostname:
        print(host['tags_by_source'])
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

host_name = 'test.host'
dog.host_tags(host_name)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

# pass a single hostname as an argument to search for the specified host
host=$1

# Find a host to add a tag to
host_name=$(curl -G "https://api.datadoghq.com/api/v1/search" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
	-d "q=hosts:$host" | cut -d'"' -f6)

curl "https://api.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
  'Datadog': [
    'host:dev-test',
    'environment:test'
  ],
  'Users': [
    'role:database'
  ]
}
["200", {
    "tags" => [
        "role:web",
        "environment:test"
    ]
}]
{
  "tags": [
    "role:database",
    "environment:test"
  ]
}

Add tags to a host

This endpoint allows you to add new tags to a host, optionally specifying where these tags come from.

ARGUMENTS
Signature

POST /v1/tags/hosts/<HOSTNAME>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

# Add tags to a host
hostname='<YOUR_HOSTNAME>'
hosts = api.Hosts.search(q='hosts:')

for host in hosts['host_list']:
    if host['name'] == hostname:
        api.Tag.create(host['name'], tags=['<KEY>:<VALUE>'])
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

host_name = 'test.host'
dog.add_tags(host_name, ["role:database", "environment:production"])
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

host=YourHostName
source=YourSource

# Find a host to add a tag to
host_name=$(curl -G "https://api.datadoghq.com/api/v1/search" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "q=hosts:$host" | cut -d'"' -f6)

curl  -X POST -H "Content-type: application/json" \
-d "{
      \"tags\" : [\"environment:production\", \"role:webserver\"]
}" \
"https://api.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}&source=${source}"
Example Response
{
  'Datadog': [
    'host:dev-test',
    'environment:test'
  ],
  'Users': [
    'role:database'
  ]
}
["201", {
    "host" => "test.metric.host",
    "tags" => ["environment:production",
        "role:web",
        "role:database",
        "environment:test"
    ]
}]
{
  "host": "test.host",
  "tags": [
    "role:database",
    "environment:test"
  ]
}

Update host tags

This endpoint allows you to update/replace all tags in an integration source with those supplied in the request.

ARGUMENTS
Signature

PUT /v1/tags/hosts/<HOSTNAME>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.Tag.update('hostname', tags=['role:database', 'environment:test'])
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

host_name = 'test.host'
dog.update_tags(host_name, ["role:web", "environment:test"])
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>
host_name=test.host

curl -X PUT -H "Content-type: application/json" \
-d '{
      "tags" : ["environment:production", "role:webserver"]
}' \
"https://api.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"
Example Response
{
    'host': 'hostname',
    'tags': [
            'role:database',
        'environment:test'
    ]
}
["201", {
    "host" => "test.metric.host",
    "tags" => [
        "role:web",
        "environment:test"
    ]
}]
{
  "host": "test.host",
  "tags": [
    "environment:production",
    "role:webserver"
  ]
}

Remove host tags

This endpoint allows you to remove all user-assigned tags for a single host.

ARGUMENTS

This endpoint takes no JSON arguments.

Signature

DELETE /v1/tags/hosts/<HOSTNAME>

Example Request
from datadog import initialize, api

options = {
    'api_key': '<YOUR_API_KEY>',
    'app_key': '<YOUR_APP_KEY>'
}

initialize(**options)

api.Tag.delete('hostname')
require 'rubygems'
require 'dogapi'

api_key = '<YOUR_API_KEY>'
app_key = '<YOUR_APP_KEY>'

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

host_name = 'test.host'
dog.detach_tags(host_name)
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

# Find a host to remove a tag from
host_name=$(curl -G "https://api.datadoghq.com/api/v1/search" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "q=hosts:" | jq -r '.results.hosts[0]')

# Add tags to the host
curl  -X POST -H "Content-type: application/json" \
-d "{\"tags\" : [\"environment:production\", \"role:webserver\"]}" \
"https://api.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"

curl -X DELETE "https://api.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"
Example Response

This endpoint does not return JSON on successful requests.

Timeboards

This endpoint is outdated. Use the new Dashboard endpoint instead.

Tracing

Learn more about tracing with Datadog and the APM terminology

The tracing API is an Agent API rather than a service side API. Submit your traces to the http://localhost:8126/v0.3/traces local endpoint so your Agent can forward them to Datadog.

Send traces

Datadog’s APM allows you to collect performance metrics by tracing your code to determine which parts of your application are slow or inefficient.

Tracing data is sent to the Datadog Agent via an HTTP API. We provide some official libraries that simplify sending metrics to the Datadog Agent, however you may want to interact directly with the API to instrument applications that cannot use the libraries or are written in languages that don’t yet have an official Datadog Tracing library.

Traces can be sent as an array of traces:

[ trace1, trace2, trace3 ]

and each trace is an array of spans:

trace1 = [ span, span2, span3 ]

and each span is a dictionary with a trace_id, span_id, resource..

Learn more about the APM & Distributed Tracing terminology

Note: Each span within a trace should use the same trace_id.

Arguments
  • trace_id - required The unique integer (64-bit unsigned) ID of the trace containing this span.
  • span_id - required The span integer (64-bit unsigned) ID.
  • name - required The span name. The span name must not be longer than 100 characters.
  • resource - required The resource you are tracing. The resource name must not be longer than 5000 characters.
  • service - required The service you are tracing. The service name must not be longer than 100 characters.
  • type - optional, default=custom, case-sensitive The type of request. The options available are web, db, cache, and custom.
  • start - required. The start time of the request in nanoseconds from the unix epoch.
  • duration - required The duration of the request in nanoseconds.
  • parent_id - optional The span integer ID of the parent span.
  • error - optional Set this value to 1 to indicate if an error occured. If an error occurs, you should pass additional information, such as the error message, type and stack information in the meta property.
  • meta - optional A set of key-value metadata. Keys and values must be strings.
  • metrics - optional A set of key-value metadata. Keys must be strings and values must be 64-bit floating point numbers.
Signature

PUT http://localhost:8126/v0.3/traces

Example Request
import random
import time
import requests
import json

# Create IDs.
TRACE_ID = random.randint(1,1000000)
SPAN_ID = random.randint(1,1000000)

# Start a timer.
# START and DURATION must be nanoseconds
START = int(time.time() * 1000000000)

# Do things...
time.sleep(2)

# Stop the timer.
DURATION= int(time.time() * 1000000000) - START

# Send the traces.
headers = {"Content-Type": "application/json"}

data = [[{
                "trace_id": TRACE_ID,
                "span_id": SPAN_ID,
                "name": "span_name",
                "resource": "/home",
                "service": "service_name",
                "type": "web",
                "start": START,
                "duration": DURATION
        }]]

requests.put("http://localhost:8126/v0.3/traces", data=json.dumps(data), headers=headers)
require 'net/http'

# Create IDs.
TRACE_ID = rand(1..1000000)
SPAN_ID = rand(1..1000000)

# Start a timer.
START = Time.now.to_f

# Do things...
sleep 2

# Stop the timer.
DURATION = ((Time.now.to_f - START)* 1000000).to_i

# Send the traces.
port = 8126
host = "127.0.0.1"
path = "/v0.3/traces"

req = Net::HTTP::Put.new(path, initheader = { 'Content-Type' => 'application/json'})

req.body = [[{ \
			"trace_id": TRACE_ID, \
			"span_id": SPAN_ID, \
			"name": "span_name", \
			"resource": "/home", \
			"service": "service_name", \
			"type": "web", \
			"start": START, \
			"duration": DURATION \
		}]]

response = Net::HTTP.new(host, port).start {|http| http.request(req) }
#!/bin/bash

# Create IDs.
TRACE_ID=($RANDOM % 1000000)
SPAN_ID=($RANDOM % 1000000)

# Start a timer.
# For the Alpine image, in order to get the time in nanoseconds,
# you may need to install coreutils ("apk add coreutils").
START=$(date +%s%N)

# Do things...
sleep 2

# Stop the timer.
DURATION=$(($(date +%s%N) - $START))

# Send the traces.
curl -X PUT -H "Content-type: application/json" \
  -d "[[{
    \"trace_id\": $TRACE_ID,
    \"span_id\": $SPAN_ID,
    \"name\": \"span_name\",
    \"resource\": \"/home\",
    \"service\": \"service_name\",
    \"type\": \"web\",
    \"start\": $START,
    \"duration\": $DURATION
}]]" \
  http://localhost:8126/v0.3/traces
Example Response
OK
OK
OK

Usage metering

This API is available to all customers. Python and Ruby clients are not yet supported.

The usage metering end-point allows you to:

  • Get Hourly Usage For Hosts and Containers
  • Get Hourly Usage For Logs
  • Get Hourly Usage For Custom Metrics
  • Get Top Custom Metrics By Hourly Average
  • Get Hourly Usage For Trace Search
  • Get Hourly Usage For Synthetics Checks
  • Get Hourly Usage For Fargate Tasks

Usage data is delayed by up to 72 hours from when it was incurred. It is retained for the past 15 months.

Get hourly usage for hosts and containers

Get Hourly Usage For Hosts and Containers.

Arguments
  • start_hr [required]: Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage beginning at this hour
  • end_hr [optional, default=1d+start_hr]: Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage ending BEFORE this hour
Response
  • container_count: Shows the total number of containers reporting via the Docker integration during the hour.
  • host_count: Contains the total number of billable infrastructure hosts reporting during a given hour. This is the sum of agent_host_count, aws_host_count, and gcp_host_count.
  • hour: The hour for the usage.
  • apm_host_count: Shows the total number of hosts using APM during the hour, these are counted as billable (except during trial periods).
  • agent_host_count: Contains the total number of infrastructure hosts reporting during a given hour that were running the Datadog Agent.
  • gcp_host_count: Contains the total number of hosts that reported via the Google Cloud integration (and were NOT running the Datadog Agent).
  • aws_host_count: Contains the total number of hosts that reported via the AWS integration (and were NOT running the Datadog Agent). When AWS or GCP hosts are also running the Datadog Agent, they are counted as Agent hosts, NOT as AWS or GCP.
Signature

GET /v1/usage/hosts

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

start_hr=$(date -v -10d +%Y-%m-%dT%H)
end_hr=$(date +%Y-%m-%dT%H)

curl -G \
    "https://api.datadoghq.com/api/v1/usage/hosts" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "start_hr=${start_hr}" \
    -d "end_hr=${end_hr}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
{
  usage: [
    {
      "container_count": 14,
      "host_count": 618,
      "hour": "2017-04-24T00",
      "apm_host_count": 588,
      "agent_host_count": 590,
      "gcp_host_count": 0,
      "aws_host_count": 28
    },
    {
      "container_count": 15,
      "host_count": 614,
      "hour": "2017-04-24T01",
      "apm_host_count": 588,
      "agent_host_count": 590,
      "gcp_host_count": 0,
      "aws_host_count": 24
    }
  ]
}

Get hourly usage for logs

Get Hourly Usage For Logs.

Arguments
  • start_hr [required]: datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage beginning at this hour
  • end_hr [optional, default=1d+start_hr]: datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage ending BEFORE this hour
Response
  • ingested_events_bytes: Contains the number of log bytes ingested.
  • indexed_events_count: Contains the number of log events indexed.
  • hour: The hour for the usage.
Signature

GET /v1/usage/logs

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

start_hr=$(date -v -10d +%Y-%m-%dT%H)
end_hr=$(date +%Y-%m-%dT%H)

curl -G \
    "https://api.datadoghq.com/api/v1/usage/logs" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "start_hr=${start_hr}" \
    -d "end_hr=${end_hr}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
{
  usage: [
    {
      "ingested_events_bytes": 3529387523,
      "indexed_events_count": 432908423,
      "hour": "2018-10-05T00"
    },
    {
      "ingested_events_bytes": 3520105821,
      "indexed_events_count": 441592101,
      "hour": "2018-10-06T01"
    }
  ]
}

Get hourly usage for custom metrics

Get Hourly Usage For Custom Metrics.

Arguments
  • start_hr [required]: Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage beginning at this hour
  • end_hr [optional, default=1d+start_hr]: Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage ending BEFORE this hour
Signature

GET /v1/usage/timeseries

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

start_hr=$(date -v -10d +%Y-%m-%dT%H)
end_hr=$(date +%Y-%m-%dT%H)

curl -G \
    "https://api.datadoghq.com/api/v1/usage/timeseries" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "start_hr=${start_hr}" \
    -d "end_hr=${end_hr}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
{
  usage: [
    {
      "num_custom_timeseries": 11,
      "hour": "2017-05-01T14"
    },
    {
      "num_custom_timeseries": 247743,
      "hour": "2017-05-01T15"
    }
  ]
}

Get top 500 custom metrics by hourly average

Get Top Custom Metrics By Hourly Average.

Arguments
  • month [required]: Datetime in ISO-8601 format, UTC, precise to month: [YYYY-MM] for usage beginning at this hour.
  • names [optional, default=None]: Comma-separated list of metric names.
Signature

GET /v1/usage/top_avg_metrics

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

month=$(date +%Y-%m)

curl -G \
    "https://api.datadoghq.com/api/v1/usage/top_avg_metrics" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "month=${month}" \
    -d "names=aws.ec2.spot_history,system.processes.number"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example 
{
  usage: [
    {
      "metric_category": "custom",
      "max_metric_hour": 7549,
      "avg_metric_hour": 7479,
      "metric_name": "aws.ec2.spot_history"
    },
    {
      "metric_category": "custom",
      "max_metric_hour": 6386,
      "avg_metric_hour": 4760,
      "metric_name": "system.processes.number"
    }
  ]
}

Get hourly usage For Trace Search.

Arguments
  • start_hr [required]: datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage beginning at this hour
  • end_hr [optional, default=1d+start_hr]: datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage ending BEFORE this hour
Response
  • indexed_events_count: Contains the number of Trace Search events indexed.
  • hour: The hour for the usage.
Signature

GET /v1/usage/traces

Example Request
# This is not yet supported by the Python Client for Datadog API
# Consult the curl example
# This is not yet supported by the Ruby Client for Datadog API
# Consult the curl example
api_key=<YOUR_API_KEY>
app_key=<YOUR_APP_KEY>

start_hr=$(date -v -10d +%Y-%m-%dT%H)
end_hr=$(date +%Y-%m-%dT%H)

curl -G \
    "https://api.datadoghq.com/api/v1/usage/traces" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "start_hr=${start_hr}" \
    -d "end_hr=${end_hr}"
Example Response
# This is not yet supported by the Python Client for Datadog API
# Consult the c