hosts

Creates, updates, deletes, gets or lists a hosts resource.

Overview

Name	hosts
Type	Resource
Id	datadog.infrastructure.hosts

Fields

The following fields are returned by SELECT queries:

list_hosts

Name	Datatype	Description
id	integer (int64)	The host ID.
name	string	The host name. (example: i-hostname)
aws_name	string	AWS name of your host. (example: mycoolhost-1)
host_name	string	The host name. (example: i-deadbeef)
aliases	array	Host aliases collected by Datadog.
apps	array	The Datadog integrations reporting metrics for the host.
is_muted	boolean	If a host is muted or unmuted.
last_reported_time	integer (int64)	Last time the host reported a metric data point.
meta	object	Metadata associated with your host.
metrics	object	Host Metrics collected.
mute_timeout	integer (int64)	Timeout of the mute applied to your host.
sources	array	Source or cloud provider associated with your host.
tags_by_source	object	List of tags for each source (AWS, Datadog Agent, Chef..).
up	boolean	Displays UP when the expected metrics are received and displays ??? if no metrics are received.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_hosts	select		filter, sort_field, sort_dir, start, count, from, include_muted_hosts_data, include_hosts_metadata	This endpoint allows searching for hosts by name, alias, or tag.<br />Hosts live within the past 3 hours are included by default.<br />Retention is 7 days.<br />Results are paginated with a max of 1000 results at a time.<br />Note: If the host is an Amazon EC2 instance, id is replaced with aws_id in the response.<br />Note: To enrich the data returned by this endpoint with security scans, see the new [api/v2/security/scanned-assets-metadata](https:​//docs.datadoghq.com/api/latest/security-monitoring/#list-scanned-assets-metadata) endpoint.
mute_host	exec	host_name		Mute a host. Note: This creates a [Downtime V2](https:​//docs.datadoghq.com/api/latest/downtimes/#schedule-a-downtime) for the host.
unmute_host	exec	host_name		Unmutes a host. This endpoint takes no JSON arguments.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
host_name	string	Name of the host to unmute.
site	string	The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both.
count	integer (int64)	Number of hosts to return. Max 1000.
filter	string	String to filter search results.
from	integer (int64)	Number of seconds since UNIX epoch from which you want to search your hosts.
include_hosts_metadata	boolean	Include additional metadata about the hosts (agent_version, machine, platform, processor, etc.).
include_muted_hosts_data	boolean	Include information on the muted status of hosts and when the mute expires.
sort_dir	string	Direction of sort. Options include asc and desc.
sort_field	string	Sort hosts by this field.
start	integer (int64)	Specify the starting point for the host search results. For example, if you set count to 100 and the first 100 results have already been returned, you can set start to 101 to get the next 100 results.

SELECT examples

list_hosts

This endpoint allows searching for hosts by name, alias, or tag.<br />Hosts live within the past 3 hours are included by default.<br />Retention is 7 days.<br />Results are paginated with a max of 1000 results at a time.<br />Note: If the host is an Amazon EC2 instance, id is replaced with aws_id in the response.<br />Note: To enrich the data returned by this endpoint with security scans, see the new [api/v2/security/scanned-assets-metadata](https:​//docs.datadoghq.com/api/latest/security-monitoring/#list-scanned-assets-metadata) endpoint.

SELECT
id,
name,
aws_name,
host_name,
aliases,
apps,
is_muted,
last_reported_time,
meta,
metrics,
mute_timeout,
sources,
tags_by_source,
up
FROM datadog.infrastructure.hosts
WHERE filter = '{{ filter }}'
AND sort_field = '{{ sort_field }}'
AND sort_dir = '{{ sort_dir }}'
AND start = '{{ start }}'
AND count = '{{ count }}'
AND from = '{{ from }}'
AND include_muted_hosts_data = '{{ include_muted_hosts_data }}'
AND include_hosts_metadata = '{{ include_hosts_metadata }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

mute_host

Mute a host. Note: This creates a Downtime V2 for the host.

EXEC datadog.infrastructure.hosts.mute_host 
@host_name='{{ host_name }}' --required, 
@@json=
'{
"end": {{ end }}, 
"message": "{{ message }}", 
"override": {{ override }}
}'
;

unmute_host

Unmutes a host. This endpoint takes no JSON arguments.

EXEC datadog.infrastructure.hosts.unmute_host 
@host_name='{{ host_name }}' --required 
;