For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/api/latest/csm-settings/list-unified-hosts.md. A documentation index is available at /llms.txt.

List unified hosts

Note: This endpoint is in Preview and may be subject to change. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/v2/csm/settings/hostshttps://api.ap2.datadoghq.com/api/v2/csm/settings/hostshttps://api.datadoghq.eu/api/v2/csm/settings/hostshttps://api.ddog-gov.com/api/v2/csm/settings/hostshttps://api.us2.ddog-gov.com/api/v2/csm/settings/hostshttps://api.uk1.datadoghq.com/api/v2/csm/settings/hostshttps://api.datadoghq.com/api/v2/csm/settings/hostshttps://api.us3.datadoghq.com/api/v2/csm/settings/hostshttps://api.us5.datadoghq.com/api/v2/csm/settings/hosts

Overview

Get the list of unified hosts for CSM, combining agent and agentless host data, with optional pagination and filtering.

Arguments

Query Strings

Name

Type

Description

page

integer

The page index for pagination (zero-based).

size

integer

The number of hosts to return per page.

query

string

A search query string to filter unified hosts.

Response

OK

The response returned when listing unified hosts.

Expand All

Field

Type

Description

data [required]

[object]

The list of unified hosts for the current page.

attributes [required]

object

Attributes of a unified host, combining data from agent and agentless sources.

account_id

string

The ID of the cloud account that the host belongs to. Present only when the host was discovered through agentless scanning.

agent_csm_vm_containers_enabled

boolean

Whether CSM Vulnerabilities is enabled for containers through the Datadog Agent. true if enabled; false if disabled.

agent_csm_vm_hosts_enabled

boolean

Whether CSM Vulnerabilities is enabled for hosts through the Datadog Agent. true if enabled; false if disabled.

agent_cws_enabled

boolean

Whether CSM Threats is enabled for this host through the Datadog Agent. true if enabled; false if disabled.

agent_posture_management

boolean

Whether CSM Misconfigurations is enabled for this host through the Datadog Agent. true if enabled; false if disabled.

agent_version

string

The version of the Datadog Agent running on this host.

agentless_posture_management

boolean

Whether CSM Misconfigurations is enabled for this host via agentless scanning. true if enabled; false if disabled.

agentless_vulnerability_scanning

boolean

Whether CSM Vulnerabilities is enabled for this host via agentless scanning. true if enabled; false if disabled.

cloud_provider

enum

The cloud provider of a host resource. Allowed enum values: aws,gcp,azure,oci

cluster_name

string

The name of the Kubernetes cluster the host belongs to, if applicable.

datadog_agent_key

string

The Datadog Agent key associated with this host. Present only for agent-sourced hosts.

env

[string]

The list of environment tags associated with this host.

host_id

int64

The internal Datadog host identifier. Present only for agent-sourced hosts.

install_method_tool

string

The tool used to install the Datadog Agent on this host.

os

string

The operating system of the host. Present only for agent-sourced hosts.

resource_type

enum

The type of cloud resource for an agentless host. Allowed enum values: aws_ec2_instance,azure_virtual_machine_instance,gcp_compute_instance,oci_instance

source [required]

enum

The source of a unified host entry, indicating whether it was discovered via agent, agentless scanning, or both. Allowed enum values: agent,agentless,both

id [required]

string

The resource identifier of the unified host.

type [required]

enum

The JSON:API type for unified host resources. The value should always be unified_host. Allowed enum values: unified_host

default: unified_host

meta [required]

object

Pagination metadata for a unified hosts list response.

page_index [required]

int64

The current page index (zero-based).

page_size [required]

int64

The number of hosts returned per page.

total_filtered [required]

int64

The total number of hosts matching the filter criteria.

total_pages [required]

int64

The total number of pages available.

{
  "data": [
    {
      "attributes": {
        "account_id": "123456789012",
        "agent_csm_vm_containers_enabled": false,
        "agent_csm_vm_hosts_enabled": true,
        "agent_cws_enabled": false,
        "agent_posture_management": true,
        "agent_version": "7.50.0",
        "agentless_posture_management": false,
        "agentless_vulnerability_scanning": true,
        "cloud_provider": "aws",
        "cluster_name": "my-cluster",
        "datadog_agent_key": "key123",
        "env": [
          "prod"
        ],
        "host_id": 12345678,
        "install_method_tool": "helm",
        "os": "linux",
        "resource_type": "aws_ec2_instance",
        "source": "agent"
      },
      "id": "i-0123456789abcdef0",
      "type": "unified_host"
    }
  ],
  "meta": {
    "page_index": 0,
    "page_size": 10,
    "total_filtered": 100,
    "total_pages": 10
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Not Authorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/csm/settings/hosts" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List unified hosts returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.csm_settings_api import CSMSettingsApi

configuration = Configuration()
configuration.unstable_operations["list_csm_unified_hosts"] = True
with ApiClient(configuration) as api_client:
    api_instance = CSMSettingsApi(api_client)
    response = api_instance.list_csm_unified_hosts()

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# List unified hosts returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_csm_unified_hosts".to_sym] = true
end
api_instance = DatadogAPIClient::V2::CSMSettingsAPI.new
p api_instance.list_csm_unified_hosts()

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// List unified hosts returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.ListCSMUnifiedHosts", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewCSMSettingsApi(apiClient)
	resp, r, err := api.ListCSMUnifiedHosts(ctx, *datadogV2.NewListCSMUnifiedHostsOptionalParameters())

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `CSMSettingsApi.ListCSMUnifiedHosts`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `CSMSettingsApi.ListCSMUnifiedHosts`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// List unified hosts returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.CsmSettingsApi;
import com.datadog.api.client.v2.model.CsmUnifiedHostsResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.listCSMUnifiedHosts", true);
    CsmSettingsApi apiInstance = new CsmSettingsApi(defaultClient);

    try {
      CsmUnifiedHostsResponse result = apiInstance.listCSMUnifiedHosts();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling CsmSettingsApi#listCSMUnifiedHosts");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
// List unified hosts returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_csm_settings::CSMSettingsAPI;
use datadog_api_client::datadogV2::api_csm_settings::ListCSMUnifiedHostsOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListCSMUnifiedHosts", true);
    let api = CSMSettingsAPI::with_config(configuration);
    let resp = api
        .list_csm_unified_hosts(ListCSMUnifiedHostsOptionalParams::default())
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * List unified hosts returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.listCSMUnifiedHosts"] = true;
const apiInstance = new v2.CSMSettingsApi(configuration);

apiInstance
  .listCSMUnifiedHosts()
  .then((data: v2.CsmUnifiedHostsResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"