Hosts
Security Monitoring is now available Security Monitoring is now available

Hosts

Get information about your live hosts in Datadog.

Get all hosts for your organization

get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/hosts

Overview

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

Arguments

Query Strings

Name

Type

Description

filter

string

String to filter search results.

sort_field

string

Sort hosts by this field.

sort_dir

string

Direction of sort. Options include asc and desc.

start

integer

Host result to start search from.

count

integer

Number of hosts to return. Max 1000.

from

integer

Number of seconds since UNIX epoch from which you want to search your hosts.

Response

OK

Response with Host information from Datadog.

Expand All

Field

Type

Description

host_list

[object]

Array of hosts.

aliases

[string]

Host aliases collected by Datadog.

apps

[string]

The Datadog integrations reporting metrics for the host.

aws_name

string

AWS name of your host.

host_name

string

The host name.

id

int64

The host ID.

is_muted

boolean

If a host is muted or unmuted.

last_reported_time

int64

Last time the host reported a metric data point.

meta

object

Metadata associated with your host.

nixV

[string]

Array of Unix versions.

metrics

object

Host Metrics collected.

cpu

double

The percent of CPU used (everything but idle).

iowait

double

The percent of CPU spent waiting on the IO (not reported for all platforms).

load

double

The system load over the last 15 minutes.

mute_timeout

int64

Timeout of the mute applied to your host.

name

string

The host name.

sources

[string]

Source or cloud provider associated with your host.

tags_by_source

object

List of tags for each source (AWS, Datadog Agent, Chef..).

<any-key>

[string]

Array of tags for a single source.

up

boolean

Displays UP when the expected metrics are received and displays ??? if no metrics are received.

total_matching

int64

Number of host matching the query.

total_returned

int64

Number of host returned.

{
  "host_list": [
    {
      "aliases": [
        "mycoolhost-1"
      ],
      "apps": [
        "agent"
      ],
      "aws_name": "mycoolhost-1",
      "host_name": "i-deadbeef",
      "id": "123456",
      "is_muted": false,
      "last_reported_time": "1565000000",
      "meta": {
        "nixV": [
          "Ubuntu"
        ]
      },
      "metrics": {
        "cpu": "99",
        "iowait": "3.2",
        "load": "0.5"
      },
      "mute_timeout": "integer",
      "name": "i-hostname",
      "sources": [
        "aws"
      ],
      "tags_by_source": {
        "<any-key>": [
          "test.example.com.host"
        ]
      },
      "up": true
    }
  ],
  "total_matching": "1",
  "total_returned": "1"
}

Invalid Parameter Error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Curl command
curl -X get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/hosts \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"

                                        
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

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

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

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

dog.search_hosts()

Get the total number of active hosts

get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/hosts/totals

Overview

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

Arguments

Query Strings

Name

Type

Description

from

integer

Number of seconds from which you want to get total number of active hosts.

Response

OK

Total number of host currently monitored by Datadog.

Expand All

Field

Type

Description

total_active

int64

Total number of active host (UP and ???) reporting to Datadog.

total_up

int64

Number of host that are UP and reporting to Datadog.

{
  "total_active": "integer",
  "total_up": "integer"
}

Invalid Parameter Error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Curl command
curl -X get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/hosts/totals \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"

                                        
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

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

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

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

dog.host_totals()

Mute a host

post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/host/{host_name}/mute

Overview

Mute a host.

Arguments

Path Parameters

Name

Type

Description

host_name [required]

string

Name of the host to mute.

Request

Body Data

Mute a host request body.

Expand All

Field

Type

Description

end

int64

POSIX timestamp in seconds when the host is unmuted. If omitted, the host remains muted until explicitly unmuted.

message

string

Message to associate with the muting of this host.

override

boolean

If true and the host is already muted, replaces existing host mute settings.

{
  "end": "1579098130",
  "message": "Muting this host for a test!",
  "override": false
}

Response

OK

Response with the list of muted host for your organization.

Expand All

Field

Type

Description

action

string

Action applied to the hosts.

end

int64

POSIX timestamp in seconds when the host is unmuted.

hostname

string

The host name.

message

string

Message associated with the mute.

{
  "action": "Muted",
  "end": "1579098130",
  "hostname": "test.host",
  "message": "Muting this host for a test!"
}

Invalid Parameter Error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Path parameters
export host_name="CHANGE_ME"
# Curl command curl -X post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/host/${host_name}/mute \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}" \ -d @- << EOF {} EOF

Unmute a host

post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/host/{host_name}/unmute

Overview

Unmutes a host. This endpoint takes no JSON arguments.

Arguments

Path Parameters

Name

Type

Description

host_name [required]

string

Name of the host to unmute.

Response

OK

Response with the list of muted host for your organization.

Expand All

Field

Type

Description

action

string

Action applied to the hosts.

end

int64

POSIX timestamp in seconds when the host is unmuted.

hostname

string

The host name.

message

string

Message associated with the mute.

{
  "action": "Muted",
  "end": "1579098130",
  "hostname": "test.host",
  "message": "Muting this host for a test!"
}

Invalid Parameter Error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example


                                        # Path parameters
export host_name="CHANGE_ME"
# Curl command curl -X post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/host/${host_name}/unmute \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"