Overview

This section details Datadogs HTTP API. It makes it easy to get data in and out of Datadog.

The Datadog API uses resource-oriented URLs, uses status codes to indicate the success or failure of requests and returns JSON from all requests. Let’s dive in and see how it works.

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

SIGNATURE

There are many client libraries that wrap the Datadog API. Check them out.

SIGNATURE

https://app.datadoghq.com/api/

Authentication

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

Manage your account’s API and application keys.

EXAMPLE

from datadog import initialize, api

options = {'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
           'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'}

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

dog = Dogapi::Client.new('9775a026f1ca7d1c6c5af9d94d9595a4', '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff')



curl "https://app.datadoghq.com/api/v1/validate?api_key=9775a026f1ca7d1c6c5af9d94d9595a4"


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 200
  • 201 Created
  • 202 accepted
  • 204 No Content
  • 301 301
  • 304 Not Modified
  • 401 401
  • 403 Forbidden 404
  • 404 Not Found
  • 409 409
  • 413 Request payload too large
  • 422 Unprocessable
  • 500 Server Error
  • Accepted 204
  • Conflict 422
  • Entity 500
  • Moved Permanently 304
  • OK 201
  • Unauthorized 403
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 our 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.

Here is some information regarding our API rate limit policy:

  • We do not rate limit on datapoint/metric submission - the limits you’d encounter would be based on your agreement
  • Rate limit for event submission is 1000 per aggregate per day per organization. An aggregate is a group of similar events.
  • Rate limit for the query_batch API call is 300 per hour per organization, it can be extended on demand
  • Rate limit for the query_snapshot API call is 60 per hour per organization, it 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 our systems from yours).

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

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

To check your timestamp is correct run:

date -u && curl -s -v https://app.datadoghq.com 2>&1 | grep Date

This output the current system’s date, and then make a request to our endpoint and grab the date on our end. If these are more than a few minutes apart, you may want to look at the time settings on your server.

There are also certain fields which are not mandatory for submission, but do require a valid input. For example, in submitting an event the priority field must be one of the four given options.

Any other text 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.

Service Checks

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

Post A check run

ARGUMENTS
  • check [required]:
    The text for the message

  • host_name[required]:
    The name of the host submitting the check

  • status [optional]:
    An integer for the status of the check:

    • 0 : OK
    • 1 : Warning
    • 2 : CRITICAL
    • 3 : UNKNOWN
  • timestamp [optional]:
    POSIX timestamp of the event.

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

  • tags [optional]:
    A list of key:val tags for this check

Signature

POST /api/v1/check_run

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

options = {'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
           'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'}

initialize(**options)

check = 'app.ok'
host = 'app1'
status = CheckStatus.OK  # equals 0

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

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

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

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


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



curl  -X POST -H "Content-type: application/json" \
-d "{
      \"check\": \"app.is_ok\",
      \"host_name\": \"app1\",
      \"timestamp\": $currenttime,
      \"status\": 0
}" \
'https://app.datadoghq.com/api/v1/check_run?api_key=9775a026f1ca7d1c6c5af9d94d9595a4'

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 api/v1/comments

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

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

curl  -X POST -H "Content-type: application/json" \
-d '{
        "message" : "There is a problem with the database."
}' \
"https://app.datadoghq.com/api/v1/comments?api_key=${api_key}&application_key=${app_key}"










Example Response

{
    'comment': {
        'handle': 'matt@example.com',
        'id': 2603645287324504065,
        'message': 'Should we use COBOL or Fortran?',
        'resource': '/api/v1/comments/2603645287324504065',
        'url': '/event/jump_to?event_id=2603645287324504065'
    }
}
["200", {
    "comment" => {
        "url" => "/event/jump_to?event_id=1382579089039712607",
        "resource" => "/api/v1/comments/1382579089039712607",
        "message" => "I have something to say.",
        "handle" => "mattp+org-carlotest141@datadoghq.com",
        "id" => 1382579089039712607
    }
}]
{
  "comment": {
    "handle": "mattp+org-carlotest141@datadoghq.com",
    "id": 1382561676571697516,
    "message": "There is a problem with the database.",
    "resource": "/api/v1/comments/1382561676571697516",
    "url": "/event/jump_to?event_id=1382561676571697516"
  }
}

Edit A Comment

ARGUMENTS
  • message [optional, default = original message]:
    The comment text.

  • handle [optional, default = Application key owner]:
    The handle of the user making the comment.

Signature

PUT api/v1/comments/:comment_id

Example Request
from datadog import initialize, api
from time import sleep

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
comment_id = "1382579089039712607"

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

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

# 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://app.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://app.datadoghq.com/api/v1/comments/${comment_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'comment': {
        'handle': 'matt@example.com',
        'id': 2603645287324504065,
        'message': 'I think differently now.',
        'resource': '/api/v1/comments/2603645287324504065',
        'url': '/event/jump_to?event_id=2603645287324504065'
    }
}
["200", {
    "comment" => {
        "url" => "/event/jump_to?event_id=1382579089039712607",
        "resource" => "/api/v1/comments/1382579089039712607",
        "message" => "I've changed my mind again",
        "handle" => "mattp+org-carlotest141@datadoghq.com",
        "id" => 1382579089039712607
    }
}]
{
  "comment": {
    "handle": "mattp+org-carlotest141@datadoghq.com",
    "id": 1382557387240472966,
    "message": "Actually, I am changing my mind.",
    "resource": "/api/v1/comments/1382557387240472966",
    "url": "/event/jump_to?event_id=1382557387240472966"
  }
}

Delete A Comment

This end point takes no JSON arguments.

Signature

DELETE api/v1/comments/:comment_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

newcomment = api.Comment.create(message='Should we use COBOL or Fortran?')
api.Comment.delete(newcomment['comment']['id'])
require 'rubygems'
require 'dogapi'

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

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

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

# Create a comment to delete. 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 deleted by the api."}' \
			"https://app.datadoghq.com/api/v1/comments?api_key=${api_key}&application_key=${app_key}" | jq -r '.comment.resource|ltrimstr("/api/v1/comments/")')
sleep 1
curl -X DELETE "https://app.datadoghq.com/api/v1/comments/${comment_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

This end point does not return JSON on successful requests.

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_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 /api/v1/downtime

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff


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://app.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,
    '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,
        "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,
  "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_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 /api/v1/downtime/:downtime_id

Example Request
from datadog import initialize, api
import time


options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
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://app.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://app.datadoghq.com/api/v1/downtime/${downtime_id}?api_key=${api_key}&application_key=${app_key}"
Example Response


{
    'active': True,
    'disabled': False,
    'end': 1420447087,
    'id': 2910,
    'message': 'Doing some testing on staging.',
    'scope': ['env:staging'],
    'start': 1420387032
}
[
    "200", {
        "end" => 1418303372,
        "disabled" => false,
        "start" => 1418224729,
        "active" => true,
        "scope" => ["env:testing"],
        "message" => "Doing some testing on staging.",
        "id" => 4336
    }
]
{
  "active": true,
  "disabled": false,
  "end": 1418303372,
  "id": 4336,
  "message": "Doing some testing on staging",
  "scope": [
    "env:staging"
  ],
  "start": 1418224729
}

Cancel Monitor Downtime

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

DELETE /api/v1/downtime/:downtime_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

# Cancel downtime
dog.cancel_downtime(1655)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
downtime_id=1656

# 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://app.datadoghq.com/api/v1/downtime?api_key=${api_key}&application_key=${app_key}" | jq '.id')

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

This end point does not return JSON on successful requests.

Cancel Monitor Downtimes By Scope

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

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

POST /api/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="9775a026f1ca7d1c6c5af9d94d9595a4"
app_key="87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"

curl -X POST -H "Content-type: application/json" -H "Accept: application/json" \
-d "{
      \"scope\": \"host:i-123\"
}" \
   "https://app.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 end point takes no JSON arguments.

Signature

GET /api/v1/downtime/:downtime_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

downtime_id=2473

curl "https://app.datadoghq.com/api/v1/downtime/${downtime_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{'active': True,
 'disabled': False,
 'end': 1420447087,
 'id': 2910,
 'message': 'Doing some testing on staging.',
 'scope': ['env:staging'],
 'start': 1420387032
 }
#
#
#
# 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.',
  '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 /api/v1/downtime

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

# Get all downtimes
print(dog.get_all_downtimes())
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff


curl -G "https://app.datadoghq.com/api/v1/downtime" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"


Example Response



[
    {
        'active': False,
        'disabled': True,
        'end': 1412793983,
        'id': 1625,
        'scope': ['env:staging'],
        'start': 1412792983
    },
    {
        'active': False,
        'disabled': True,
        'end': None,
        'id': 1626,
        'scope': ['*'],
        'start': 1412792985
    }
]
[
    "200", [{
        "end" => 1412793983,
        "disabled" => true,
        "start" => 1412792983,
        "active" => false,
        "scope" => ["env:staging"],
        "id" => 1625
    }, {
        "end" => nil,
        "disabled" => true,
        "start" => 1412792985,
        "active" => false,
        "scope" => ["*"],
        "id" => 1626
    }]
]
[
  {
    "active": false,
    "disabled": true,
    "end": 1412793983,
    "id": 1625,
    "scope": [
      "env:staging"
    ],
    "start": 1412792983
  },
  {
    "active": false,
    "disabled": true,
    "end": null,
    "id": 1626,
    "scope": [
      "*"
    ],
    "start": 1412792985
  }
]

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/:embed_id.

ARGUMENTS

This end point takes no JSON arguments.

Signature

GET api/v1/graph/embed

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

# Initialize API Client
api_key = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

# Get all with API Call
dog.get_all_embeds()
api_key="9775a026f1ca7d1c6c5af9d94d9595a4"
app_key="87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"





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


Example Response

{
    "embedded_graphs": [
        {
            "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
            "template_variables": [],
            "html": '<iframe src="https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true" width="600" height="300" frameBorder="0"></iframe>',
            "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" => '<iframe src="https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true" width="600" height="300" frameBorder="0"></iframe>',
        "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": "<iframe src=\"https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true\" width=\"600\" height=\"300\" frameBorder=\"0\"></iframe>",
      "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/:embed_id. 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.

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 api/v1/graph/embed

Example Request
from datadog import initialize, api
import json

# Intialize request parameters including API/APP key
options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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="9775a026f1ca7d1c6c5af9d94d9595a4"
app_key="87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"







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://app.datadoghq.com/api/v1/graph/embed?api_key=${api_key}&application_key=${app_key}"















Example Response

{
    "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables": [],
    "html": '<iframe src="https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true" width="600" height="300" frameBorder="0"></iframe>',
    "graph_title": "Embed created through API",
    "revoked": False,
    "dash_url": None,
    "shared_by": 3658,
    "dash_name": None
}
{
    "embed_id" => "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables" => [],
    "html" => '<iframe src="https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true" width="600" height="300" frameBorder="0"></iframe>',
    "graph_title" => "Embed created through API",
    "revoked" => false,
    "dash_url" => nil,
    "shared_by" => 3658,
    "dash_name" => nil
}
{
  "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
  "template_variables": [],
  "html": "<iframe src=\"https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true\" width=\"600\" height=\"300\" frameBorder=\"0\"></iframe>",
  "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
  • 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.
  • template_variables [optional, default=None]:
    Replace template variables in queries with form $var. To replace $var with val, use var=val as a parameter for each template variable you wish to replace. If any template variables are missing values in the iframe source url, then (*) is used as the value.
Signature

GET api/v1/graph/embed/:embed_id

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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="9775a026f1ca7d1c6c5af9d94d9595a4"
app_key="87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"


embed_id="5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"



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




Example Response

{
    "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables": [],
    "html": '<iframe src="https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true" width="600" height="300" frameBorder="0"></iframe>',
    "graph_title": "Embed created through API",
    "revoked": False,
    "dash_url": None,
    "shared_by": 3658,
    "dash_name": None
}
{
    "embed_id" => "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
    "template_variables" => [],
    "html" => '<iframe src="https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true" width="600" height="300" frameBorder="0"></iframe>',
    "graph_title" => "Embed created through API",
    "revoked" => false,
    "dash_url" => nil,
    "shared_by" => 3658,
    "dash_name" => nil
}
{
  "embed_id": "5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c",
  "template_variables": [],
  "html": "<iframe src=\"https://app.datadoghq.com/graph/embed?token=5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c&height=300&width=600&legend=true\" width=\"600\" height=\"300\" frameBorder=\"0\"></iframe>",
  "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 end point takes no JSON arguments.

Signature

GET api/v1/graph/embed/:embed_id/enable

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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="9775a026f1ca7d1c6c5af9d94d9595a4"
app_key="87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"
embed_id="5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"






curl -X GET "https://app.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 end point takes no JSON arguments.

Signature

GET api/v1/graph/embed/:embed_id/revoke

Example Request
from datadog import initialize, api

# Intialize request parameters including API/APP key
options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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="9775a026f1ca7d1c6c5af9d94d9595a4"
app_key="87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"



embed_id="5f585b01c81b12ecdf5f40df0382738d0919170639985d3df5e2fc4232865b0c"


curl -X GET "https://app.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 end point 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](/graphing/event_stream/#markdown-events). Use msg_text with the Datadog Ruby library
  • date_happened [optional, default = now]:
    POSIX timestamp of the event.
  • priority [optional, default = normal]:
    The priority of the event: normal or low.
  • host [optional, default=None]:
    Host name to associate with the event. 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 its 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, bitbucket
    Complete list of source attribute values
Signature

POST /api/v1/events

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

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

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

# 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://app.datadoghq.com/api/v1/events?api_key=9775a026f1ca7d1c6c5af9d94d9595a4'



Example Response

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

Signature

GET /api/v1/events/:event_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

event_id = '1375909614428331251'
dog.get_event(event_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
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://app.datadoghq.com/api/v1/events?api_key=9775a026f1ca7d1c6c5af9d94d9595a4" | jq -r '.event.url|ltrimstr("https://app.datadoghq.com/event/event?id=")')
sleep 5

curl "https://app.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"
  }
}

Delete an event

This end point allows you to delete an event.

ARGUMENTS

This end point takes no JSON arguments.’

Signature

DELETE /api/v1/events/:event_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

dog.delete_event(1375909614428331251)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff


event_id=1377281704830403917


curl -X DELETE "https://app.datadoghq.com/api/v1/events/${event_id}?api_key=${api_key}&application_key=${app_key}"
Example Response



{
    "deleted_event_id": "2603387619536318140"
}
[
    "200", {
        "deleted_event_id" => "1375909614428331251"
    }
]


{
  "deleted_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.
Signature

GET /api/v1/events

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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

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


dog.stream(start_time, end_time, : priority => "normal", : tags => ["application:web"])
# Note: this end point 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=application:web,version:1" \
    -d "api_key=9775a026f1ca7d1c6c5af9d94d9595a4" \
    -d "application_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" \
    'https://app.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

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 api/v1/graph/snapshot

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = '9775a026f1ca7d1c6c5af9d94d9595a4'
app_key = '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'

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

end_ts = Time.now().to_i
start_ts = end_ts - (60 * 60)
dog.graph_snapshot("system.load.1{*}", start_ts, end_ts)

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=9775a026f1ca7d1c6c5af9d94d9595a4" \
    -d "application_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" \
    'https://app.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

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 /api/v1/host/:hostname/mute

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff



curl -X POST -H "Content-type: application/json" \
-d '{
      "message": "Muting this host for a test!"
}' "https://app.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 end point takes no JSON arguments.

Signature

POST /api/v1/host/:hostname/unmute

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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

hostname = "test.host"
dog.unmute_host(hostname)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff





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

Integrations

Configure your Datadog integrations via Datadog API, current configurable integrations are:

Available Endpoints are:

  • To Create an integration in Datadog:
    POST /api/v1/integration/<source_type_name>

  • To edit an integration configuration:
    PUT /api/v1/integration/<source_type_name>

  • To get an integration status:
    GET /api/v1/integration/<source_type_name>

  • To delete an integration from Datadog:
    DELETE /api/v1/integration/<source_type_name>

AWS

Configure your Datadog-AWS integration directly through Datadog API.
Read more about Datadog-AWS integration

ARGUMENTS
  • account_id [required]:
    Your AWS Account ID without dashes.
    Consult our Datadog AWS integration to learn more about your AWS account ID.

  • role_name [required]:
    Your Datadog role delegation name.
    Consult our Datadog AWS integration to learn more about your AWS account Role name.

  • filter_tags [optional, default=None]:
    Array of EC2 tags (in the form key:value) defines a filter that Datadog use 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
    Read more about EC2 tagging in 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.

Signature

https://app.datadoghq.com/api/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 
# List AWS Accounts (role-based only) in Datadog
curl -X GET "https://app.datadoghq.com/api/v1/integration/aws?api_key=${api_key}&application_key=${app_key}"



# Create an AWS Account in Datadog
curl -X POST -H "Content-type: application/json" \
-d '{
        "account_id": "YOUR_AWS_ACCOUNT_ID",
        "filter_tags": ["env:staging"],
        "host_tags": ["account:staging","account:customer1"],
        "role_name": "DatadogAWSIntegrationRole"
}' \
"https://app.datadoghq.com/api/v1/integration/aws?api_key=${api_key}&application_key=${app_key}"




# Delete an AWS Account in Datadog
curl -X DELETE -H "Content-type: application/json" \
-d '{
        "account_id": "YOUR_AWS_ACCOUNT_ID",
        "role_name": "DatadogAWSIntegrationRole"
}' \
"https://app.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 
OK

PagerDuty

Configure your Datadog-PagerDuty integration directly through Datadog API.
Read more about Datadog-PagerDuty integration

ARGUMENTS
  • services [required]:
    Array of PagerDuty service objects. Learn how to configure you Datadog service with 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 [required]:
    Your PagerDuty accounts personalized sub-domain name.

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

  • api_token [required]:
    Your PagerDuty API token.

  • run_check [optional, default=false]:
    Determines if the integration install check is run before returning a response.

    • If true:

      • The install check is run
      • If there’s an error in the configuration the error is returned
      • If there’s no error, 204 No Content response code is returned
    • If false:

      • We return a 202 accepted
      • Install check is run after returning a response
Signature

https://app.datadoghq.com/api/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 
curl -v -X PUT -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>"
        }
      ],
      "subdomain": "my-pd",
      "schedules": ["https://my-pd.pagerduty.com/schedules#PCPYT4M", "https://my-pd.pagerduty.com/schedules#PKTPB7P"],
      "api_token": "<PAGERDUTY_TOKEN>"
  }' \
"https://app.datadoghq.com/api/v1/integration/pagerduty?api_key=${api_key}&application_key=${app_key}&run_check=true"

curl -v "https://app.datadoghq.com/api/v1/integration/pagerduty?api_key=${api_key}&application_key=${app_key}"

curl -v -X DELETE "https://app.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

Slack

Configure your Datadog-Slack integration directly through Datadog API.
Read more about Datadog-Slack integration

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.

  • channels [required]:
    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.

  • run_check [optional, default=false]:
    Determines if the integration install check is run before returning a response.

    • If true:

      • The install check is run
      • If there’s an error in the configuration the error is returned
      • If there’s no error, 204 No Content response code is returned
    • If false:

      • We return a 202 accepted
      • Install check is run after returning a response
Signature

https://app.datadoghq.com/api/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 
curl -v -X POST -H "Content-type: application/json" \
-d '{
    "service_hooks": [
      {
        "account": "Main_Account",
        "url": "https://hooks.slack.com/services/1/1"
      },
      {
        "account": "doghouse",
        "url": "https://hooks.slack.com/services/2/2"
      }
    ],
    "channels": [
      {
        "channel_name": "#private",
        "transfer_all_user_comments": "false",
        "account": "Main_Account"
      },
      {
        "channel_name": "#heresachannel",
        "transfer_all_user_comments": "false",
        "account": "doghouse"
      }
    ]
  }' \
"https://app.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}&run_check=true"

curl -v -X PUT -H "Content-type: application/json" \
-d '{
    "service_hooks": [
      {
        "account": "Main_Account",
        "url": "https://hooks.slack.com/services/1/1"
      },
      {
        "account": "doghouse",
        "url": "https://hooks.slack.com/services/2/2"
      }
    ],
    "channels": [
      {
        "channel_name": "#private",
        "transfer_all_user_comments": "false",
        "account": "Main_Account"
      },
      {
        "channel_name": "#heresachannel",
        "transfer_all_user_comments": "false",
        "account": "doghouse"
      }
    ]
}' \
"https://app.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}&run_check=true"

curl -v "https://app.datadoghq.com/api/v1/integration/slack?api_key=${api_key}&application_key=${app_key}"


curl -v -X DELETE "https://app.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

Webhooks

Configure your Datadog-Webhooks integration directly through Datadog API.
Read more about 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_payloag 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.

  • run_check [optional, default=false]:
    Determines if the integration install check is run before returning a response.

    • If true:

      • The install check is run
      • If there’s an error in the configuration the error is returned
      • If there’s no error, 204 No Content response code is returned
    • If false:

      • We return a 202 accepted
      • Install check is run after returning a response
Signature

https://app.datadoghq.com/api/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 
curl -v -X POST -H "Content-type: application/json" \
-d '{
    "hooks": [
      {
        "name": "somehook",
        "url": "http://requestb.in/v1srg7v1",
        "use_custom_payload": "false",
        "custom_payload": "",
        "encode_as_form": "false",
        "headers": ""
      }
    ]
}' \
"https://app.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}&run_check=true"

curl -v -X PUT -H "Content-type: application/json" \
-d '{
    "hooks": [
      {
        "name": "anotherone",
        "url": "http://requestb.in/v1srg7v1"
      }
    ]
}' \
"https://app.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}&run_check=true"

curl -v "https://app.datadoghq.com/api/v1/integration/webhooks?api_key=${api_key}&application_key=${app_key}"

curl -v -X DELETE "https://app.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

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, our 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 time series per host, where a time series is defined as a unique combination of metric name and tag.

Get list of active metrics

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
Signature

GET https://app.datadoghq.com/api/v1/metrics

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

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

curl -G \
    "https://app.datadoghq.com/api/v1/metrics" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
    -d "from=${from_time}"




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 time series points

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

ARGUMENTS

  • series [optional, default=None]:
    To submit multiple metrics, you may pass a JSON array where each item in the array contains the following arguments. To submit a single metric, you may pass the following arguments as separate arguments.

  • metric [required]:
    The name of the time series

  • points [required]:
    A JSON array of points. Each point is of the form:
    [[POSIX_timestamp, numeric_value], ...]
    Note that the timestamp should be in seconds, must be current, and the numeric value is 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 [required]:
    The name of the host that produced the metric.

  • tags [optional, default=None]:
    A list of tags associated with the metric.

Signature

POST https://app.datadoghq.com/api/v1/series

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = "9775a026f1ca7d1c6c5af9d94d9595a4"

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, :type => 'counter')
end



currenttime=$(date +%s)


curl  -X POST -H "Content-type: application/json" \
-d "{ \"series\" :
         [{\"metric\":\"test.metric\",
          \"points\":[[$currenttime, 20]],
          \"type\":\"gauge\",
          \"host\":\"test.example.com\",
          \"tags\":[\"environment:test\"]}
        ]
}" \
'https://app.datadoghq.com/api/v1/series?api_key=9775a026f1ca7d1c6c5af9d94d9595a4'









Query time series points

This end point allows you to query for metrics from any time period.

ARGUMENTS
  • from [required]:
    Seconds from the unix epoch
  • to [required]:
    Seconds to the unix epoch
  • start [optional, default=None]:
    Seconds since the unix epoch
  • end [optional, default=None]:
    Seconds since the unix epoch
  • query [required]:
    The query strong
Signature

GET https://app.datadoghq.com/api/v1/query

Example Request
from datadog import initialize, api
import time

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = "9775a026f1ca7d1c6c5af9d94d9595a4"
application_key = "87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"

dog = Dogapi::Client.new(api_key, application_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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
to_time=$(date +%s)
from_time=$(date -v -1d +%s)

curl -G \
    "https://app.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 end point takes no JSON arguments.’

Signature

GET /api/v1/metrics/:metric_name

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

metric = 'system.cpu.idle'

api.metric.list(metric_name=metric)
require 'rubygems'
require 'dogapi'

api_key = "9775a026f1ca7d1c6c5af9d94d9595a4"


dog = Dogapi::Client.new(api_key)


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

api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff


metric_name="system.net.bytes_sent"


curl "https://app.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 /api/v1/metrics/:metric_name

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

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 = "9775a026f1ca7d1c6c5af9d94d9595a4"

dog = Dogapi::Client.new(api_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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff


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://app.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"
}

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

ARGUMENTS
  • type [required]:
    The type of the monitor, chosen from:

    • metric alert
    • service check
    • event alert
    • composite
  • 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 (5, 10, 15, or 30), last#h (1, 2, or 4), or last_1d
    • space_aggr avg, sum, min, or max
    • tags one or more tags (comma-separated), or *
    • key a ‘key’ in key:value tag syntax; defines a separate alert for each tag in the group (multi-alert)
    • operator <, <=, >, >=, ==, or !=
    • # an integer or decimal number used to set the threshold

    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.
    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.
    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=None]:
    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}
    • notify_no_data a boolean indicating whether this monitor notifies when data stops reporting. Default: false

    • 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

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

    • timeout_h the number of hours of the monitor not reporting data before it 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
    Metric Alert Options

    These options only apply to metric alerts.

    • thresholds a dictionary of thresholds by threshold type. Currently we have 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}`
      
Signature

POST /api/v1/monitor

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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

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://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}"
Example Response

{'creator': {'email': 'matt@example.com',
             'handle': 'matt@example.com',
             'id': 1896,
             'name': u'Matt'},
 'id': 2081,
 'message': 'We may need to add web hosts if this is consistently high.',
 'name': 'Bytes received on host0',
 '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 /api/v1/monitor/:monitor_id

Example Request
from datadog import initialize, api


options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}


initialize(**options)


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

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

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

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

# Create a monitor to show
monitor_id=$(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."
  }' \
    "https://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}" | jq '.id')

curl -G "https://app.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.” default=“dynamic, based on query
  • message [optional, default = dynamic, based on query]: A message to include with notifications for this monitor. Email notifications can be sent to specific users by using the same ‘@username’ notation as events.
  • options [optional, default=None]:
    Refer to the create monitor documentation for details on the available options.
  • tags [optional, default=None]:
    A list of tags to associate with your monitor. This can help you categorize and filter monitors
Signature

PUT /api/v1/monitor/:monitor_id

Example Request
from datadog import initialize,  api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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

# Create a monitor to edit
monitor_id=$(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."
  }' \
    "https://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}" | jq '.id')

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


{
    'id': 2081,
    'message': 'We may need to add web hosts if this is consistently high.',
    'name': 'Bytes received on host0',
    'options': {'notify_audit': False, 'notify_no_data': False, 'silenced': {}},
    'org_id': 2,
    'overall_state': 'No Data',
    'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
    'type': 'metric alert',
    '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 end point takes no JSON arguments.

Signature

DELETE /api/v1/monitor/:monitor_id

Example Request
from datadog import initialize, api


options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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

# Create a monitor to delete
monitor_id=$(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."
  }' \
    "https://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}" | jq '.id')

curl -X DELETE "https://app.datadoghq.com/api/v1/monitor/${monitor_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'deleted_monitor_id': 2081
}
["200", {
    "deleted_monitor_id" => 62625
}]
{
  "deleted_monitor_id": 59409
}

Get all monitor details

ARGUMENTS
  • group_states [optional, default=None]:
    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 [required]:
    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.
Signature

GET /api/v1/monitor

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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


curl -G "https://app.datadoghq.com/api/v1/monitor" \
     -d "api_key=${api_key}" \
     -d "application_key=${app_key}"


Example Response

[
    {'creator': {
        'email': 'matt@example.com',
        'handle': 'matt@example.com',
        'id': 1896,
        'name': u'Matt'
    },
        'id': 2085,
        'message': u'',
        'name': '**system.net.bytes_rcvd** over **host:host0** was **> 100** on average during the **last 1h**.',
        'options': {'notify_audit': False, 'notify_no_data': False, 'silenced': {}},
        'org_id': 2,
        '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"
    }]
]
[
  {
    "id": 91879,
    "message": "We may need to add web hosts if this is consistently high.",
    "name": "Bytes received on host0",
    "options": {
      "notify_audit": false,
      "notify_no_data": false,
      "silenced": {}
    },
    "org_id": 1499,
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
    "type": "metric alert",
    "multi": false,
    "created": "2015-12-18T16:34:14.014039+00:00",
    "modified": "2015-12-18T16:34:14.014039+00:00"
  },
  {
    "id": 91875,
    "message": "",
    "name": "**system.net.bytes_rcvd** over **host:host0** was **> 100** on average during the **last 1h**.",
    "options": {
      "escalation_message": "",
      "no_data_timeframe": false,
      "notify_audit": true,
      "notify_no_data": false,
      "renotify_interval": null,
      "silenced": {},
      "timeout_h": null
    },
    "org_id": 1499,
    "query": "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100",
    "type": "metric alert",
    "multi": false,
    "created": "2015-12-18T16:34:14.014039+00:00",
    "modified": "2015-12-18T16:34:14.014039+00:00"
  }
]

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 as well eg:
    resolve: [{"monitor_id": "group_1"}, {"monitor_id": "group_2"}]
Signature

POST /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/or APP key below
# with the ones for your account

api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

monitor_id= <YOUR_MONITOR_ID>
group_1=<YOUR_FIRST_GROUP>
group_2=<YOUR_FIRST_GROUP>

curl -X POST -H "Content-type: application/json" \
-d '{
"resolve": [
          {"${monitor_id}": "${group_1}"},
          {"${monitor_id}": "${group_2}"}
      ]
}' \
    "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 end point takes no JSON arguments.

Signature

POST /api/v1/monitor/mute_all

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

# Mute all alerts
dog.mute_monitors()

api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff


curl -X POST "https://app.datadoghq.com/api/v1/monitor/mute_all?api_key=${api_key}&application_key=${app_key}"


Example Response


{
    'active': True,
    'disabled': False,
    'end': None,
    'id': 2728,
    'message': None,
    'scope': ['*'],
    'start': 1419440110
}
[
    "200", {
        "end" => nil,
        "disabled" => false,
        "start" => 1412805855,
        "active" => true,
        "scope" => ["*"],
        "id" => 1647
    }
]
{
  "active": true,
  "disabled": false,
  "end": null,
  "id": 1648,
  "scope": [
    "*"
  ],
  "start": 1412805856
}

Unmute all monitors

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

ARGUMENTS

This end point takes no JSON arguments.

Signature

POST /api/v1/monitor/unmute_all

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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


curl -X POST "https://app.datadoghq.com/api/v1/monitor/unmute_all?api_key=${api_key}&application_key=${app_key}"




Example Response

This end point does not return JSON on successful requests.

Mute a monitor

ARGUMENTS
  • scope [optional, default=None]:
    The scope to apply the mute to, e.g. role:db.
  • end [optional, default=None]:
    A POSIX timestamp for when the mute should end.
Signature

POST /api/v1/monitor/:monitor_id/mute

Example Request

from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}


initialize(**options)


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

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

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

# Mute a monitor
dog.mute_monitor(62628)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
monitor_id=62628

# Create a monitor to mute
monitor_id=$(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."
  }' \
    "https://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}" | jq '.id')

curl -X POST "https://app.datadoghq.com/api/v1/monitor/${monitor_id}/mute?api_key=${api_key}&application_key=${app_key}"
Example Response



{
    'id': 2088,
    'message': 'We may need to add web hosts if this is consistently high.',
    'name': 'Bytes received on host0',
    'options': {
        'notify_audit': False,
        'notify_no_data': False,
        'silenced': {
            '*': None
        }
    },
    'org_id': 2,
    'overall_state': 'No Data',
    'query': 'avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100',
    'type': 'metric alert',
    '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 /api/v1/monitor/:monitor_id/unmute

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}


initialize(**options)


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

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

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

# Unmute all alerts
dog.unmute_monitor(62628)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
monitor_id=62628

# Create a monitor to unmute
monitor_id=$(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."
  }' \
    "https://app.datadoghq.com/api/v1/monitor?api_key=${api_key}&application_key=${app_key}" | jq '.id')

curl -X POST "https://app.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"
}

Organizations

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. Currently 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 api/v1/org

Example Request
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -X POST -H "Content-type: application/json" \
    -d '{
        "name" :"My Org",
        "subscription" :{"type":"pro"},
        "billing" :{"type":"parent_billing"}
}' \
    "https://app.datadoghq.com/api/v1/org?api_key=${api_key}&application_key=${app_key}"
Example Response

{
  "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

ARGUMENTS
  • public_id [required]:
    The public id of the organization.
Signature

GET api/v1/org/:public_id

Example Request
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
public_id=axd2s

curl -X GET "https://app.datadoghq.com/api/v1/org/${public_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
  "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 api/v1/org/:public_id

Example Request
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
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://app.datadoghq.com/api/v1/org/${public_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
  "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

ARGUMENTS
  • idp_file [required]:
    The path to the XML metadata file you wish to upload.
Signature

POST api/v1/org/:public_id/idp_metadata

Example Request
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
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://app.datadoghq.com/api/v1/org/${public_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
  "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"
    }
  }
}

Screenboards

This endpoint allows you to programmatically create, update delete and query Screenboards. Find more about Screenboard.

Create a Screenboard

Arguments
  • board_title [required]:
    The name of the dashboard.
  • description [optional, default=None]:
    A description of the dashboard’s content.
  • widgets [required]:
    A list of widget definitions.
  • template_variables [optional, default=None]:
    A list of template variables for using Dashboard templating.
  • width [optional, default=None]:
    Screenboard width in pixels
  • height [optional, default=None]:
    Height in pixels.
  • read_only [optional, default=False]:
    The read-only status of the screenboard.
Signature

POST /api/v1/screen

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

board_title = "My Screenboard"
description = "An informative screenboard."
width = 1024
widgets = [{
    "type": "image",
    "height": 20,
    "width": 32,
    "y": 7,
    "x": 32,
    "url": "https://path/to/image.jpg"
}]
template_variables = [{
    "name": "host1",
    "prefix": "host",
    "default": "host:my-host"
}]

api.Screenboard.create(board_title=board_title,
                       description=description,
                       widgets=widgets,
                       template_variables=template_variables,
                       width=width)
require 'rubygems'
require 'dogapi'

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

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

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

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

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







Example Response

{
    'description': 'An informative screenboard.',
    'created': '2015-12-17T21:29:40.890824+00:00',
    'modified': '2015-12-17T21:29:40.890824+00:00',
    'read_only': False,
    'widgets': [{'height': 20,
                 'type': 'image',
                 'url': 'https://path/to/image.jpg',
                 'width': 32,
                 'x': 32,
                 'y': 7}],
    'id': 811,
    'template_variables': [{
        'default': 'host:my-host',
        'name': 'host1',
        'prefix': 'host'}],
    'board_title': 'My Screenboard',
    'width': 1024
}
[
    "200", {
        "board_title" => "dogapi test",
        "width" => 1024,
        "height" => 768,
        "id" => 7952,
        "widgets" => [{
            "url" => "https://path/to/image.jpg",
            "height" => 20,
            "width" => 32,
            "y" => 7,
            "x" => 32,
            "type" => "image"
        }],
        "created" => "2015-12-17T21:29:40.890824+00:00",
        "modified" => "2015-12-17T21:29:40.890824+00:00",
        "read_only" => false
    }
]
{
  "board_title": "dogapi test",
  "height": 768,
  "id": 7953,
  "widgets": [
    {
      "height": 20,
      "type": "image",
      "url": "https://path/to/image.jpg",
      "width": 32,
      "x": 32,
      "y": 7
    }
  ],
  "width": 1024,
  "created": "2015-12-17T23:06:06.703087+00:00",
  "modified": "2015-12-17T23:06:06.705087+00:00",
  "read_only": "false"
}

Update a Screenboard

Override a Screenboard configuration in Datadog.

Note: You must send the entire original Screenboard configuration along with your updates otherwise the original widgets are erased.

ARGUMENTS
  • board_title [required]: The name of the dashboard.
  • description [optional, default=None]: A description of the dashboard’s content.
  • widgets [required]: A list of widget definitions.
  • template_variables [optional, default=None]: A list of template variables for using Dashboard templating.
  • width [optional, default=None]: Screenboard width in pixels
  • height [optional, default=None]: Screenboard height in pixels.
  • read_only [optional, default=False]: The read-only status of the screenboard.
Signature

PUT /api/v1/screen/:board_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)
board_id = 2551
board_title = "My Screenboard"
description = "An informative screenboard."
width = 1024
widgets = [{
    "type": "image",
    "height": 20,
    "width": 32,
    "y": 7,
    "x": 32,
    "url": "https://path/to/image.jpg"
}]
template_variables = [{
    "name": "host1",
    "prefix": "host",
    "default": "host:my-host"
}]

api.Screenboard.update(board_id,
                       board_title=board_title,
                       description=description,
                       widgets=widgets,
                       template_variables=template_variables,
                       width=width)
require 'rubygems'
require 'dogapi'

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

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


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

result = dog.update_screenboard(board_id, board)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

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






Example Response

{'board_title': 'My Screenboard',
 'read_only': False,
 'description': 'An informative screenboard.',
 'created': '2016-06-01T08:59:24.636877+00:00',
 'modified': '2016-06-01T09:41:06.482175+00:00',
 'width': 1024,
 'template_variables': [{'default': 'host:my-host',
                         'prefix': 'host',
                         'name': 'host1'}],
 'widgets': [{'url': 'https://path/to/image.jpg',
              'height': 20,
              'width': 32,
              'y': 7,
              'x': 32,
              'type': 'image'}],
 'id': 2551}
["200", {
    "board_title" => "dogapi test",
    "read_only" => false,
    "created" => "2016-06-01T08:59:24.636877+00:00",
    "modified" => "2016-06-01T09:27:25.608805+00:00",
    "height" => 768,
    "width" => 1024,
    "widgets" => [{
        "url" => "https://path/to/image.jpg",
        "height" => 20,
        "width" => 32,
        "y" => 7,
        "x" => 32,
        "type" => "image"
    }],
    "id" => 7953
}]
{
  "board_title": "dogapi test",
  "read_only": false,
  "created": "2016-06-01T08:59:24.636877+00:00",
  "modified": "2016-06-01T09:06:32.481009+00:00",
  "height": 768,
  "width": 1024,
  "widgets": [
    {"url": "https://path/to/image.jpg",
      "height": 20,
      "width": 32,
      "y": 7,
      "x": 32,
    "type": "image"}
  ],
"id": 7953}

Delete a Screenboard

Delete an existing Screenboard.

ARGUMENTS

This end point takes no JSON arguments.

Signature

DELETE /api/v1/screen/:board_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

api.Screenboard.delete(811)
require 'rubygems'
require 'dogapi'

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

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

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

# Create a screenboard to delete
board_id=$(curl -X POST -H "Content-type: application/json" \
-d '{
        "width": 1024,
        "height": 768,
        "board_title": "dogapi tests",
        "widgets": [
            {
              "type": "image",
              "height": 20,
              "width": 32,
              "y": 7,
              "x": 32,
              "url": "https://path/to/image.jpg"
            }
        ]
  }' \
"https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}" | jq '.id')


curl -X DELETE \
"https://app.datadoghq.com/api/v1/screen/${board_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

This end point does not return JSON on successful requests.

Get a Screenboard

Fetch an existing Screenboard’s definition.

ARGUMENTS

This end point takes no JSON arguments.

Signature

GET /api/v1/screen/:board_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

api.Screenboard.get(811)
require 'rubygems'
require 'dogapi'

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

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

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

# Create a screenboard to get
board_id=$(curl -X POST -H "Content-type: application/json" \
-d '{
        "width": 1024,
        "height": 768,
        "board_title": "dogapi tests",
        "widgets": [
            {
              "type": "image",
              "height": 20,
              "width": 32,
              "y": 7,
              "x": 32,
              "url": "https://path/to/image.jpg"
            }
        ]
  }' \
"https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}" | jq '.id')


curl -X GET \
"https://app.datadoghq.com/api/v1/screen/${board_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'description': 'An informative screenboard.',
    'created': '2015-12-17T21:29:40.890824+00:00',
    'modified': '2015-12-17T21:39:20.770834+00:00',
    'read_only': False,
    'widgets': [{
        'height': 20,
        'type': 'image',
        'url': 'https://path/to/image.jpg',
                'width': 32,
                'x': 32,
                'y': 7}],
    'id': 811,
        'template_variables': [{'default': 'host:my-host',
                                'name': 'host1',
                                'prefix': 'host'}],
        'title': 'My Screenboard',
        'width': 1024
}
["200", {
    "board_title" => "dogapi test",
    "width" => 1024,
    "height" => 768,
    "id" => 6334,
    "widgets" => [{
        "url" => "http://path/to/image.jpg",
        "height" => 20,
        "width" => 32,
        "y" => 7,
        "x" => 32,
        "type" => "image"
    }],
    "created" => "2015-12-17T21:29:40.890824+00:00",
    "modified" => "2015-12-17T21:39:20.770834+00:00",
    "read_only" => false
}]
{
  "board_title": "dogapi test",
  "height": 768,
  "id": 6334,
  "widgets": [
    {
      "height": 20,
      "type": "image",
      "url": "http://path/to/image.jpg",
      "width": 32,
      "x": 32,
      "y": 7
    }
  ],
  "width": 1024,
  "created": "2015-12-17T23:06:06.703087+00:00",
  "modified": "2015-12-17T23:12:26.726234+00:00",
  "read_only": "false"
}

Get all Screenboards

Fetch all of your Screenboards’ definitions.

ARGUMENTS

This end point takes no JSON arguments.

Signature

GET /api/v1/screen

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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




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

Example Response

{
    'screenboards': [
        {
            'description': 'This has all the new hotness.',
            'id': '2551',
            'resource': '/api/v1/screen/2551',
            'title': 'New and Improved Screenboard',
            'created': '2015-12-17T21:29:40.890824+00:00',
            'modified': '2015-12-17T21:39:20.770834+00:00',
            'read_only': False
        },
        {
            'description': 'And they are marvelous.',
            'id': '2552',
            'resource': '/api/v1/screen/2552',
            'title': 'My First Metrics',
            'created': '2015-12-17T21:29:40.890824+00:00',
            'modified': '2015-12-17T21:39:20.770834+00:00',
            'read_only': False
        }
    ]
}
[
    "200", {
        "screenboards" => [{
            "created" => "2015-12-17T20:00:25.050990+00:00",
            "resource" => "/api/v1/screen/6334",
            "id" => 6334,
            "modified" => "2015-12-17T20:00:25.051176+00:00",
            "title" => "dogapi test",
            "read_only" => false
        }, {
            "created" => "2015-12-17T20:00:25.868731+00:00",
            "resource" => "/api/v1/screen/2",
            "id" => 2,
            "modified" => "2015-12-17T20:00:25.868752+00:00",
            "title" => "Database Screen Board",
            "read_only" => false
        }]
    }
]

[
  {
    'description': 'This has all the new hotness.',
    'id': '2551',
    'resource': '/api/v1/screen/2551',
    'title': 'New and Improved Screenboard',
    'created': '2015-12-17T23:06:06.703087+00:00',
    'modified': '2015-12-17T23:12:26.726234+00:00',
    'read_only': 'false'
  },
  {
    'description': 'And they are marvelous.',
    'id': '2552',
    'resource': '/api/v1/screen/2552',
    'title': 'My First Metrics',
    'created': '2015-12-17T23:06:06.703087+00:00',
    'modified': '2015-12-17T23:12:26.726234+00:00',
    'read_only': 'false'
  }
]

Share a Screenboard

Share an existing Screenboard’s with a public URL.

ARGUMENTS

This end point takes no JSON arguments.

Signature

POST /api/v1/screen/share/:board_id

Example Request
from datadog import initialize, api


options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

api.Screenboard.share(812)
require 'rubygems'
require 'dogapi'

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

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

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

# Create a screenboard to share
board_id=$(curl -X POST -H "Content-type: application/json" \
-d '{
        "width": 1024,
        "height": 768,
        "board_title": "dogapi tests",
        "widgets": [
            {
              "type": "image",
              "height": 20,
              "width": 32,
              "y": 7,
              "x": 32,
              "url": "https://path/to/image.jpg"
            }
        ]
  }' \
"https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}" | jq '.id')



curl -X POST \
"https://app.datadoghq.com/api/v1/screen/share/${board_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'board_id': 812,
    'public_url': 'https://p.datadoghq.com/sb/20756e0cd4'
}
["200", {
    "board_id" => 6334, "public_url" => "https://p.datadoghq.com/sb/20756e0cd4"
}]
{
  "board_id": 6334,
  "public_url": "https://p.datadoghq.com/sb/20756e0cd4"
}

Revoke a shared a Screenboard

Revoke a currently shared Screenboard’s.

ARGUMENTS

This end point takes no JSON arguments.

Signature

DELETE /api/v1/screen/share/:board_id

Example Request
from datadog import initialize, api


options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Share it
api.Screenboard.share(812)

# Revoke the sharing
api.Screenboard.revoke(812)
require 'rubygems'
require 'dogapi'

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

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

board_id = '6334'

# Share it
dog.share_screenboard(board_id)

# Revoke the sharing
dog.revoke_screenboard(board_id)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
board_id=6334

# Create a screenboard to share
board_id=$(curl -X POST -H "Content-type: application/json" \
-d '{
        "width": 1024,
        "height": 768,
        "board_title": "dogapi tests",
        "widgets": [
            {
              "type": "image",
              "height": 20,
              "width": 32,
              "y": 7,
              "x": 32,
              "url": "https://path/to/image.jpg"
            }
        ]
  }' \
"https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}" | jq '.id')

# Share it
curl -X POST \
"https://app.datadoghq.com/api/v1/screen/share/${board_id}?api_key=${api_key}&application_key=${app_key}"

# Revoke the sharing
curl -X DELETE \
"https://app.datadoghq.com/api/v1/screen/share/${board_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

This end point does not return JSON on successful requests.

This end point allows you to search for entities from the last 24 hours in Datadog. The currently searchable entities are:

  • hosts
  • metrics
ARGUMENTS
  • q [required]:
    The query string
QUERY LANGUAGE

Search queries allow for limited faceting. Available facets are:

  • hosts
  • metrics

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

Un-faceted queries are of the form:

query_string

Faceted queries are of the form:

facet:query_string

Signature

GET /api/v1/search

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

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

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

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

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

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

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

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








Example Response


{
    'results': {
        'hosts': [
            'test.metric.host',
            'test.tag.host'
        ],
        'metrics': [
            'test.metric.metric',
            'test.tag.metric'
        ]
    }
}
["200", {
    "results" => {
        "metrics" => ["test.metric"],
        "hosts" => [
            "test.another.example.com",
            "test.example.com",
            "test.host",
            "test.metric.host",
            "test.tag.host"
        ]
    }
}]
{
  "results": {
    "hosts": [
      "test.another.example.com",
      "test.example.com",
      "test.host",
      "test.metric.host",
      "test.tag.host"
    ],
    "metrics": [
      "test.metric"
    ]
  }
}

Tags

The tag end point 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
Signature

GET /api/v1/tags/hosts

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

print api.Tag.get_all()
require 'rubygems'
require 'dogapi'

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

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

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

curl "https://app.datadoghq.com/api/v1/tags/hosts?api_key=${api_key}&application_key=${app_key}"




Example Response



{
    "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
  • source [optional, default=None]:
    Only show tags from a particular source. Otherwise shows all tags.
    Complete list of source attribute values
  • by_source [optional, default=False]:
    Return tags grouped by source.
Signature

GET /api/v1/tags/hosts/:host_name

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Get tags by host id.
hosts = api.Infrastructure.search(q='hosts:')
print api.Tag.get(hosts['results']['hosts'][0])
require 'rubygems'
require 'dogapi'

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

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

host_name = 'test.host'
dog.host_tags(host_name)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

# 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://app.datadoghq.com/api/v1/search" \
    -d "api_key=${api_key}" \
    -d "application_key=${app_key}" \
	-d "q=hosts:$host" | cut -d'"' -f6)

curl "https://app.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'tags': [
        'role:database',
        'env:test'
    ]
}
["200", {
    "tags" => [
        "role:web",
        "environment:test"
    ]
}]
{
  "tags": [
    "role:database",
    "environment:test"
  ]
}

Add tags to a host

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

ARGUMENTS
Signature

POST /api/v1/tags/hosts/:host_name

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)
hosts = api.Infrastructure.search(q='hosts:')
api.Tag.create(hosts['results']['hosts'][0], tags=["role:codesample"])
require 'rubygems'
require 'dogapi'

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

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

host_name = 'test.host'
dog.add_tags(host_name, ["role:database", "environment:production"])
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
host=YourHostName

# Find a host to add a tag to
host_name=$(curl -G "https://app.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://app.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'host': 'hostname',
    'tags': [
        'role:webserver',
        'env:production'
    ]
}
["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 end point allows you to update all tags for a given host.

ARGUMENTS
Signature

PUT /api/v1/tags/hosts/:host_name

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

api.Tag.update('hostname', tags=['role:database', 'environment:test'])
require 'rubygems'
require 'dogapi'

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

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

host_name = 'test.host'
dog.update_tags(host_name, ["role:web", "environment:test"])
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
host_name=test.host

curl -X PUT -H "Content-type: application/json" \
-d '{
      "tags" : ["environment:production", "role:webserver"]
}' \
"https://app.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 end point allows you to remove all tags for a given host.

ARGUMENTS
Signature

DELETE /api/v1/tags/hosts/:host_name

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)


api.Tag.delete('hostname')
require 'rubygems'
require 'dogapi'

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

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

host_name = 'test.host'
dog.detach_tags(host_name)
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

# Find a host to remove a tag from
host_name=$(curl -G "https://app.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://app.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"

curl -X DELETE "https://app.datadoghq.com/api/v1/tags/hosts/${host_name}?api_key=${api_key}&application_key=${app_key}"
Example Response

This end point does not return JSON on successful requests.

Timeboards

This endpoint allows you to programmatically create, update delete and query Timeboards. Find more about Timeboard.

Create a Timeboard

Arguments
  • title [required]:
    The name of the dashboard.
  • description [optional, default=None]:
    A description of the dashboard’s content.
  • graphs [optional, default=None]:
    A list of graph definitions. Graph definitions follow this form:

    • title [required]:
      The name of the graph.
    • definition [optional, default=None]:
      The graph definition. Example:
      {"requests": [{"q": "system.cpu.idle{*} by {host}"}
  • template_variables [optional, default=None]:
    A list of template variables for using Dashboard templating. Template variable definitions follow this form:

    • name [required]:
      The name of the variable.
    • prefix [optional, default=None]:
      The tag prefix associated with the variable. Only tags with this prefix appear in the variable dropdown.
    • default [optional, default=None]:
      The default value for the template variable on dashboard load.
Signature

POST /api/v1/dash

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

read_only = True
api.Timeboard.create(title=title,
                     description=description,
                     graphs=graphs,
                     template_variables=template_variables,
                     read_only=read_only)
require 'rubygems'
require 'dogapi'

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

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


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

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



curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }],
      "read_only": "True"
}' \
"https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}"

Example Response


{
    'dash': {
        'description': 'An informative timeboard.',
        'created': '2015-12-17T21:29:40.890824+00:00',
        'modified': '2015-12-17T21:29:40.890824+00:00',
        'read_only': 'True',
        'graphs': [
            {
                'definition': {'events': [],
                               'requests': [{'q': 'avg:system.mem.free{*}'}],
                               'viz': 'timeseries'},
                'title': 'Average Memory Free'
            }],
        'id': 4952,
        'template_variables': [
            {
                'default': 'host:my-host',
                'name': 'host1',
                'prefix': 'host'
            }],
        'title': 'My Timeboard'},
    'resource': '/api/v1/dash/4952',
    'url': '/dash/dash/4952'
}
[
    "200", {
        "dash" => {
            "graphs" => [{
                "definition" => {
                    "viz" => "timeseries",
                    "events" => [],
                    "requests " => [{
                        "q" => "avg:system.mem.free{*}"
                    }]
                },
                "title" => "Average Memory Free"
            }],
            "description" => "And they are marvelous.",
            "id" => 2552,
            "title" => "My First Metrics"
        },
        "url" => "/dash/dash/2552",
        "resource" => "/api/v1/dash/2552",
        "created" => "2015-12-17T21:29:40.890824+00:00",
        "modified" => "2015-12-17T21:29:40.890824+00:00"
    }
]
{
  "dash": {
    "description": "A dashboard with memory info.",
    "graphs": [
      {
        "definition": {
          "events": [],
          "requests": [
            {
              "q": "avg:system.mem.free{*}"
            }
          ]
        },
        "title": "Average Memory Free"
      }
    ],
    "id": 2532,
    "title": "Average Memory Free Shell"
  },
  "resource": "/api/v1/dash/2532",
  "url": "/dash/dash/2532",
  "created": "2015-12-17T23:06:06.703087+00:00",
  "modified": "2015-12-17T23:06:06.726234+00:00",
  "read_only": "true"
}

Update a Timeboard

Arguments
  • title [required]:
    The name of the dashboard.
  • description [optional]:
    A description of the dashboard’s contents.
  • graphs [optional]:
    A list of graph definitions. Graph definitions follow this form:

    • title [required]:
      The name of the graph.
    • definition [required]:
      The graph definition. Read the Graph Guide for more on graphs. Example:
      {"requests": [{"q": "system.cpu.idle{*} by {host}"}
  • template_variables [optional, default=None]:
    A list of template variables for using Dashboard templating. Template variable definitions follow this form:

    • name [required]:
      The name of the variable.

    • prefix [optional, default=None]:
      The tag prefix associated with the variable. Only tags with this prefix appear in the variable dropdown.

    • default [optional, default=None]:
      The default value for the template variable on dashboard load.

Signature

PUT /api/v1/dash/:dash_id

Example Request
from datadog import initialize, api

options = {'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
           'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'}

initialize(**options)

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

api.Timeboard.update(
    4952,
    title=title,
    description=description,
    graphs=graphs,
    template_variables=template_variables,
    read_only=read_only,
)
require 'rubygems'
require 'dogapi'

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

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

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

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

# Create a dashboard to get. Use jq (http://stedolan.github.io/jq/download/) to get the dash id.
dash_id=$(curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
  }' \
"https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}" | jq '.dash.id')

curl  -X PUT -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Sum of Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "sum:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Sum Memory Free Shell",
      "description" : "An updated dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
}' \
"https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
Example Response


{
    'dash':
    {
        'description': 'A new and improved timeboard!',
        'created': '2015-12-17T21:29:40.890824+00:00',
        'modified': '2015-12-17T21:39:20.770834+00:00',
        'read_only': True,
        'graphs': [{
            'definition': {
                'events': [],
                'requests': [{'q': 'avg:system.mem.free{*} by {host}'}],
                'viz': 'timeseries'
            },
            'title': 'Average Memory Free By Host'
        }],
        'id': 4952,
        'template_variables': [{'default': 'host:my-host',
                                'name': 'host1',
                                'prefix': 'host'}],
        'title': 'My Timeboard'},
    'resource': '/api/v1/dash/4952',
    'url': '/dash/dash/4952'
}
[
    "200", {
        "dash" => {
            "graphs" => [{
                "definition" => {
                    "viz" => "timeseries",
                    "events" => [],
                    "requests " => [{
                        "q" => "avg:system.mem.free{*}"
                    }]
                },
                "title" => "Average Memory Free"
            }],
            "description" => "This has all the new hotness.",
            "id" => 2551,
            "title" => "New and Improved Dashboard"
        },
        "url" => "/dash/dash/2551",
        "resource" => "/api/v1/dash/2551",
        "created" => "2015-12-17T21:29:40.890824+00:00",
        "modified" => "2015-12-17T21:39:20.770834+00:00"
    }
]
{
  "dash": {
    "description": "A dashboard with memory info.",
    "graphs": [
      {
        "definition": {
          "events": [],
          "requests": [
            {
              "q": "sum:system.mem.free{*}"
            }
          ]
        },
        "title": "Sum of Memory Free"
      }
    ],
    "id": 2532,
    "title": "Sum Memory Free Shell"
  },
  "resource": "/api/v1/dash/2532",
  "url": "/dash/dash/2532",
  "created": "2015-12-17T23:06:06.703087+00:00",
  "modified": "2015-12-17T23:12:26.726234+00:00",
  "read_only": "false"
}

Delete a Timeboard

Delete an existing timeboard. This end point takes no JSON arguments.

Signature

DELETE /api/v1/dash/:dash_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

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

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

newboard = api.Timeboard.create(title=title,
                                description=description,
                                graphs=graphs,
                                template_variables=template_variables)

api.Timeboard.delete(newboard['dash']['id'])
require 'rubygems'
require 'dogapi'

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

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

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

# Create a dashboard to delete. Use jq (http://stedolan.github.io/jq/download/) to get the dash id.
dash_id=$(curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
  }' \
"https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}" | jq '.dash.id')

curl -X DELETE "https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"

Example Response

This end point does not return JSON on successful requests.

Get all Timeboards

Fetch all of your timeboard’ definitions.

Arguments

This end point takes no JSON arguments.

Signature

GET /api/v1/dash

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

print api.Timeboard.get_all()
require 'rubygems'
require 'dogapi'

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

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

dog.get_dashboards
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

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




Example Response


{
    'dashes': [
        {
            'description': 'This has all the new hotness.',
            'id': '2551',
            'resource': '/api/v1/dash/2551',
            'title': 'New and Improved Dashboard',
            'created': '2015-12-17T21:29:40.890824+00:00',
            'modified': '2015-12-17T21:39:20.770834+00:00'
        },
        {
            'description': 'And they are marvelous.',
            'id': '2552',
            'resource': '/api/v1/dash/2552',
            'title': 'My First Metrics',
            'created': '2015-12-17T21:29:40.890824+00:00',
            'modified': '2015-12-17T21:39:20.770834+00:00',
            'read_only': True
        }
    ]
}
[
    "200", {
        "dashes" => [{
            "title" => "My Dashboard",
            "resource" => "/api/v1/dash/2473",
            "id" => "2473",
            "description" => "An informative dashboard.",
            "created" => "2015-12-17T21:29:40.890824+00:00",
            "modified" => "2015-12-17T21:39:20.770834+00:00"
        }, {
            "title" => "My First Metrics",
            "resource" => "/api/v1/dash/2552",
            "id" => "2552",
            "description" => "And they are marvelous.",
            "created" => "2015-12-17T20:09:33.890824+00:00",
            "modified" => "2015-12-17T20:19:22.770834+00:00",
            "read_only" => true
        }]
    }
]
{
  "dashes": [
    {
      "description": "An informative dashboard.",
      "id": "2473",
      "resource": "/api/v1/dash/2473",
      "title": "My Dashboard",
      "created": "2015-12-12T23:06:06.703087+00:00",
      "modified": "2015-12-12T23:12:26.726234+00:00",
      "read_only": "true"
    },
    {
      "description": "This has all the new hotness.",
      "id": "2551",
      "resource": "/api/v1/dash/2551",
      "title": "New and Improved Dashboard",
      "created": "2015-12-17T23:06:06.703087+00:00",
      "modified": "2015-12-17T23:12:26.726234+00:00",
      "read_only": "true"
    }
  ]
}

Get a Timeboard

Fetch an existing dashboard’s definition.

Arguments

This end point takes no JSON arguments.

Signature

GET /api/v1/dash/:dash_id

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

api.Timeboard.get(4953)
require 'rubygems'
require 'dogapi'

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

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

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

# Create a dashboard to get. Use jq (http://stedolan.github.io/jq/download/) to get the dash id.
dash_id=$(curl  -X POST -H "Content-type: application/json" \
-d '{
      "graphs" : [{
          "title": "Average Memory Free",
          "definition": {
              "events": [],
              "requests": [
                  {"q": "avg:system.mem.free{*}"}
              ]
          },
          "viz": "timeseries"
      }],
      "title" : "Average Memory Free Shell",
      "description" : "A dashboard with memory info.",
      "template_variables": [{
          "name": "host1",
          "prefix": "host",
          "default": "host:my-host"
      }]
  }' \
"https://app.datadoghq.com/api/v1/dash?api_key=${api_key}&application_key=${app_key}" | jq '.dash.id')

curl "https://app.datadoghq.com/api/v1/dash/${dash_id}?api_key=${api_key}&application_key=${app_key}"
Example Response

{
    'dash': {
        'description': 'A new and improved timeboard!',
        'created': '2015-12-17T21:29:40.890824+00:00',
        'modified': '2015-12-17T21:39:20.770834+00:00',
        'read_only': True,
        'graphs': [
            {
                'definition': {
                    'events': [],
                    'requests': [{'q': 'avg:system.mem.free{*} by {host}'}],
                    'viz': 'timeseries'},
                'title': 'Average Memory Free By Host'
            }
        ],
        'id': 4953,
        'template_variables': [
            {
                'default': 'host:my-host',
                'name': 'host1',
                'prefix': 'host'}],
        'title': 'My Timeboard'
    },
    'resource': '/api/v1/dash/4953',
    'url': '/dash/dash/4953'
}
[
    "200", {
        "dash" => {
            "graphs" => [{
                "definition" => {
                    "viz" => "timeseries",
                    "events" => [],
                    "requests " => [{
                        "q" => "avg:system.mem.free{*}"
                    }]
                },
                "title" => "Average Memory Free"
            }],
            "description" => "desc",
            "id" => 2542,
            "title" => "foobar"
        },
        "url" => "/dash/dash/2542",
        "resource" => "/api/v1/dash/2542",
        "created" => "2015-12-17T21:29:40.890824+00:00",
        "modified" => "2015-12-17T21:39:20.770834+00:00",
        "read_only" => true
    }
]
{
  "dash": {
    "description": "An informative dashboard.",
    "graphs": [
      {
        "definition": {
          "events": [],
          "requests": [
            {
              "q": "avg:system.mem.free{*}"
            }
          ],
          "viz": "timeseries"
        },
        "title": "Average Memory Free"
      }
    ],
    "id": 2473,
    "title": "My Dashboard",
  },
  "resource": "/api/v1/dash/2473",
  "url": "/dash/dash/2473",
  "created": "2015-12-17T23:06:06.703087+00:00",
  "modified": "2015-12-17T23:12:26.726234+00:00",
  "read_only": "true"
}

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.

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.
  • resource - Required. The resource you are tracing.
  • service - _Required._The service name.
  • type - Required. The type of request.
  • 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 dictionary of key-value metadata. e.g. tags.

Learn more about the APM (tracing) terminology

Note: You may send multiple spans within a trace array and each span within a trace should use the same trace_id. You may also send multiple traces.

Signature

PUT http://localhost:8126/v0.3/traces

Example Request
import random
import time 
import requests

# Create IDs.
TRACE_ID = random.randint(1,1000000)
SPAN_ID = random.randint(1,1000000)

# Start a timer.
START = int(time.time() * 1000000)

# Do things...
time.sleep(2)

# Stop the timer.
DURATION= int(time.time() * 1000000) - 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 = 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.
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

Send services

Arguments
  • service - _Required._The service name as a dictionary key, Learn more.
  • app - Required. The name of the application.
  • app_type - Required. The type of application.
Signature

PUT http://localhost:8126/v0.3/traces

Example Request
import requests

# Send the service.
headers = {'Content-type': 'application/json'}
data = {"service_name": {"app": "my-app","app_type": "web"}}

requests.put('http://localhost:8126/v0.3/services', headers=headers, data = data)
require 'net/http'

port = 8126
host = "127.0.0.1"
path = "/v0.3/services"


req = Net::HTTP::Put.new(path, initheader = { 'Content-Type' => 'application/json'})

req.body = {"service_name": {"app": "my-app","app_type": "web"}}

response = Net::HTTP.new(host, port).start {|http| http.request(req) }
#!/bin/bash

# Send the service.
curl -X PUT -H "Content-type: application/json" \
  -d "{
    \"service_name\": {
      \"app\": \"my-app\",
      \"app_type\": \"web\"
    }
}" \
  http://localhost:8126/v0.3/services
Example Response

OK
OK
OK

Usage metering

This API is currently in private beta. 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 Custom Metrics
  • Get Top Custom Metrics By Hourly Average

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. For Pro plans, these are counted as billable (except during trial periods). For Enterprise plans, APM hosts are included in the price of infrastructure hosts (see host_count) and not billed separately.
  • 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 https://app.datadoghq.com/api/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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

start_hr=$(date -v -10d +%Y-%m-%dT%H)
end_hr=$(date +%Y-%m-%dT%H)

curl -G \
    "https://app.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 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 https://app.datadoghq.com/api/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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

start_hr=$(date -v -10d +%Y-%m-%dT%H)
end_hr=$(date +%Y-%m-%dT%H)

curl -G \
    "https://app.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 https://app.datadoghq.com/api/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=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

month=$(date +%Y-%m)

curl -G \
    "https://app.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"
    }
  ]
}

Users

Create, edit, and disable users. Read more about your team management

Create user

ARGUMENTS
  • handle [required]:
    The user handle, must be a valid email.
  • name [optional, default=None]:
    The name of the user.
  • access_role [optional, default=st]:
    The access role of the user. Choose from:
    • st (standard user),
    • adm (admin user),
    • ro (read-only user).
      Note: users can be created with admin access role only with application keys belonging to administrators.
Signature

POST api/v1/user

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Create user
api.User.create(handle='test@datadoghq.com', name='test user')
require 'rubygems'
require 'dogapi'

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

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

dog.create_user(: handle => 'test@datadoghq.com', : name => 'test user')
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

curl -X POST -H "Content-type: application/json" \
    -d '{"handle":"test@datadoghq.com","name":"test user"}' \
    "https://app.datadoghq.com/api/v1/user?api_key=${api_key}&application_key=${app_key}"



Example Response

{'user': {
    'verified': False,
    'name': 'test user',
    'access_role': 'st',
    'disabled': False,
    'role': None,
    'is_admin': False,
    'handle': 'test@datadoghq.com',
    'email': 'test@datadoghq.com'
}
}
["200", {
	"user"=>{
		"handle"=>"test@datadoghq.com",
		"name"=>"test user",
		"verified"=>false,
		"access_role"=>"st",
		"disabled"=>false,
		"role"=>nil,
		"is_admin"=>false,
		"email"=>"test@datadoghq.com"
}}]
{"user": {
    "handle": "test@datadoghq.com",
    "name": "test user",
    "access_role": "st",
    "verified": false,
    "disabled": false,
    "role": null,
    "is_admin": false,
    "email": "test@datadoghq.com"
  }
}

Get user

ARGUMENTS
  • handle [required]:
    The handle of the user.
Signature

GET api/v1/user/:handle

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Get one user
api.User.get('test@datadoghq.com')
require 'rubygems'
require 'dogapi'

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

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

dog.get_user('test@datadoghq.com')
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
user=test@datadoghq.com

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




Example Response

{
    'user':
    {
        'verified': False,
        'name': 'test user',
        'access_role': 'st',
        'disabled': False,
        'role': None,
        'is_admin': False,
        'handle': 'test@datadoghq.com',
        'email': 'test@datadoghq.com'
    }}
["200", {
    "user" => {
        "handle" => "test@datadoghq.com",
        "name" => "test user",
        "access_role" => "st",
        "verified" => false,
        "disabled" => false,
        "role" => nil,
        "is_admin" => false,
        "email" => "test@datadoghq.com"
    }
}]
{
  "user":{
    "handle":"test@datadoghq.com",
    "name":"test user",
    "access_role":"st",
    "verified":false,
    "disabled":false,
    "role":null,
    "is_admin":false,
    "email":"test@datadoghq.com"
  }
}

Get all users

ARGUMENTS

This end point takes no JSON arguments.

Signature

GET api/v1/user

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Get all users
api.User.get_all()
require 'rubygems'
require 'dogapi'

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

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

dog.get_all_users()
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff

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





Example Response

{'users': [
    {
        'verified': False,
        'name': 'test user',
                'access_role': 'st',
                'disabled': False,
                'role': None,
                'is_admin': False,
                'handle': 'test@datadoghq.com',
                'email': 'test@datadoghq.com'
    }, {
        'verified': False,
        'name': 'alt name',
                'access_role': 'ro',
                'disabled': False,
                'role': None,
                'is_admin': False,
                'handle': 'test2@datadoghq.com',
                'email': 'test+1@datadoghq.com'
    }
]}
["200", {
    "users" => [{
        "handle" => "test@datadoghq.com",
        "name" => "test user",
        "access_role" => "st",
        "verified" => false,
        "disabled" => false,
        "role" => nil,
        "is_admin" => false,
        "email" => "test@datadoghq.com"
    }, {
        "handle" => "test2@datadoghq.com",
        "name" => "alt name",
        "access_role" => "ro",
        "verified" => false,
        "disabled" => false,
        "role" => nil,
        "is_admin" => false,
        "email" => "test+1@datadoghq.com"
    }]
}]
{"users": [
    {
      "handle": "test@datadoghq.com",
      "name": "test user",
      "access_role": "st",
      "verified": false,
      "disabled": false,
      "role": null,
      "is_admin": false,
      "email": "test@datadoghq.com"
    },
    {
      "handle": "test2@datadoghq.com",
      "name": "alt name",
      "access_role": "ro",
      "verified": false,
      "disabled": false,
      "role": null,
      "is_admin": false,
      "email": "test+1@datadoghq.com"
}]}

Update user

Can only be used with application keys belonging to administrators.

ARGUMENTS
  • handle [required]:
    The handle of the user.
  • name [optional, default=None]:
    The new name of the user.
  • email [optional, default=None]:
    The new email of the user.
  • disabled [optional, default=None]:
    The new disabled status of the user.
  • access_role [optional, default=st]:
    The access role of the user. Choose from:
    • st (standard user),
    • adm (admin user),
    • ro (read-only user).
Signature

PUT api/v1/user/:handle

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Update user
api.User.update('test@datadoghq.com', name='alt name',
                email='test+1@datadoghq.com')
require 'rubygems'
require 'dogapi'

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

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

dog.update_user('test@datadoghq.com', : email => 'test+1@datadoghq.com', : name => 'alt name')
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
user=test@datadoghq.com

curl -X PUT -H "Content-type: application/json" \
    -d '{"email":"test+1@datadoghq.com","name":"alt user", "access_role":"ro"}' \
    "https://app.datadoghq.com/api/v1/user/${user}?api_key=${api_key}&application_key=${app_key}"


Example Response

{
    'user': {
        'verified': False,
        'name': 'alt name',
        'access_role': 'st',
        'disabled': False,
        'role': None,
        'is_admin': False,
        'handle': 'test@datadoghq.com',
        'email': 'test+1@datadoghq.com'
    }
}
["200", {
    "user" => {
        "handle" => "test@datadoghq.com",
        "name" => "alt name",
        "access_role" => "st",
        "verified" => false,
        "disabled" => false,
        "role" => nil,
        "is_admin" => false,
        "email" => "test+1@datadoghq.com"
    }
}]
{
  "user":{
    "handle":"test@datadoghq.com",
    "name":"alt user",
    "access_role":"ro",
    "verified":false,
    "disabled":false,
    "role":null,
    "is_admin":false,
    "email":"test+1@datadoghq.com"
  }
}

Disable user

Can only be used with application keys belonging to administrators.

ARGUMENTS
  • handle [required]:
    The handle of the user.
Signature

DELETE api/v1/user/:handle

Example Request
from datadog import initialize, api

options = {
    'api_key': '9775a026f1ca7d1c6c5af9d94d9595a4',
    'app_key': '87ce4a24b5553d2e482ea8a8500e71b8ad4554ff'
}

initialize(**options)

# Disable user
api.User.delete('test@datadoghq.com')
require 'rubygems'
require 'dogapi'

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

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

dog.disable_user('test@datadoghq.com')
api_key=9775a026f1ca7d1c6c5af9d94d9595a4
app_key=87ce4a24b5553d2e482ea8a8500e71b8ad4554ff
user=test@datadoghq.com

curl -X DELETE "https://app.datadoghq.com/api/v1/user/${user}?api_key=${api_key}&application_key=${app_key}"




Example Response

{
    'message': 'User test@datadoghq.com disabled'
}
["200", {
    "message" => "User test@datadoghq.com disabled"
}]
{
  "message": "User test@datadoghq.com disabled"
}