Get a configuration deployment by ID

This endpoint is in Preview and may introduce breaking changes. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/unstable/fleet/deployments/{deployment_id}https://api.ap2.datadoghq.com/api/unstable/fleet/deployments/{deployment_id}https://api.datadoghq.eu/api/unstable/fleet/deployments/{deployment_id}https://api.ddog-gov.com/api/unstable/fleet/deployments/{deployment_id}https://api.us2.ddog-gov.com/api/unstable/fleet/deployments/{deployment_id}https://api.datadoghq.com/api/unstable/fleet/deployments/{deployment_id}https://api.us3.datadoghq.com/api/unstable/fleet/deployments/{deployment_id}https://api.us5.datadoghq.com/api/unstable/fleet/deployments/{deployment_id}

Overview

Retrieve detailed information about a specific deployment using its unique identifier. This endpoint returns comprehensive information about a deployment, including:

  • Deployment metadata (ID, type, filter query)
  • Total number of target hosts
  • Current high-level status (pending, running, succeeded, failed)
  • Estimated completion time
  • Configuration operations that were or are being applied
  • Detailed host list: A paginated array of hosts included in this deployment with individual host status, current package versions, and any errors

The host list provides visibility into the per-host execution status, allowing you to:

  • Monitor which hosts have completed successfully
  • Identify hosts that are still in progress
  • Investigate failures on specific hosts
  • View current package versions installed on each host (including initial, target, and current versions for each package)

Pagination: Use the limit and page query parameters to paginate through hosts. The response includes pagination metadata in the meta.hosts field with information about the current page, total pages, and total host count. The default page size is 50 hosts, with a maximum of 100.

This endpoint requires the hosts_read permission.

Arguments

Path Parameters

Name

Type

Description

deployment_id [required]

string

The unique identifier of the deployment to retrieve.

Query Strings

Name

Type

Description

limit

integer

Maximum number of hosts to return per page. Default is 50, maximum is 100.

page

integer

Page index for pagination (zero-based). Use this to retrieve subsequent pages of hosts.

Response

OK

Response containing a single deployment.

Expand All

Field

Type

Description

data

object

A deployment that defines automated configuration changes for a fleet of hosts.

attributes [required]

object

Attributes of a deployment in the response.

config_operations

[object]

Ordered list of configuration file operations to perform on the target hosts.

file_op [required]

enum

Type of file operation to perform on the target configuration file.

  • merge-patch: Merges the provided patch data with the existing configuration file. Creates the file if it doesn't exist.
  • delete: Removes the specified configuration file from the target hosts. Allowed enum values: merge-patch,delete

file_path [required]

string

Absolute path to the target configuration file on the host.

patch

object

Patch data in JSON format to apply to the configuration file. When using merge-patch, this object is merged with the existing configuration, allowing you to add, update, or override specific fields without replacing the entire file. The structure must match the target configuration file format (for example, YAML structure for Datadog Agent config). Not applicable when using the delete operation.

estimated_end_time_unix

int64

Estimated completion time of the deployment as a Unix timestamp (seconds since epoch).

filter_query

string

Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.

high_level_status

string

Current high-level status of the deployment (for example, "pending", "running", "completed", "failed").

hosts

[object]

Paginated list of hosts in this deployment with their individual statuses. Only included when fetching a single deployment by ID. Use the limit and page query parameters to navigate through pages. Pagination metadata is included in the response meta.hosts field.

error

string

Error message if the deployment failed on this host.

hostname

string

The hostname of the agent.

status

string

Current deployment status for this specific host.

versions

[object]

List of packages and their versions currently installed on this host.

current_version

string

The current version of the package on the host.

initial_version

string

The initial version of the package on the host before the deployment started.

package_name

string

The name of the package.

target_version

string

The target version that the deployment is attempting to install.

packages

[object]

List of packages to deploy to target hosts. Present only for package upgrade deployments.

name [required]

string

The name of the package to deploy.

version [required]

string

The target version of the package to deploy.

total_hosts

int64

Total number of hosts targeted by this deployment.

id [required]

string

Unique identifier for the deployment.

type [required]

enum

The type of deployment resource. Allowed enum values: deployment

default: deployment

meta

object

Metadata for a single deployment response, including pagination information for hosts.

hosts

object

Pagination details for the list of hosts in a deployment.

current_page

int64

Current page index (zero-based).

page_size

int64

Number of hosts returned per page.

total_hosts

int64

Total number of hosts in this deployment.

total_pages

int64

Total number of pages available.

{
  "data": {
    "attributes": {
      "config_operations": [
        {
          "file_op": "merge-patch",
          "file_path": "/datadog.yaml",
          "patch": {
            "apm_config": {
              "enabled": true
            },
            "log_level": "debug",
            "logs_enabled": true
          }
        }
      ],
      "estimated_end_time_unix": 1699999999,
      "filter_query": "env:prod AND service:web",
      "high_level_status": "pending",
      "hosts": [
        {
          "error": "",
          "hostname": "web-server-01.example.com",
          "status": "succeeded",
          "versions": [
            {
              "current_version": "7.51.0",
              "initial_version": "7.51.0",
              "package_name": "datadog-agent",
              "target_version": "7.52.0"
            }
          ]
        }
      ],
      "packages": [
        {
          "name": "datadog-agent",
          "version": "7.52.0"
        }
      ],
      "total_hosts": 42
    },
    "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
    "type": "deployment"
  },
  "meta": {
    "hosts": {
      "current_page": 0,
      "page_size": 50,
      "total_hosts": 150,
      "total_pages": 3
    }
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Not Found

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

                  # Path parameters
export deployment_id="abc-def-ghi"
# 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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/unstable/fleet/deployments/${deployment_id}" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
Get a configuration deployment by ID returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.fleet_automation_api import FleetAutomationApi

configuration = Configuration()
configuration.unstable_operations["get_fleet_deployment"] = True
with ApiClient(configuration) as api_client:
    api_instance = FleetAutomationApi(api_client)
    response = api_instance.get_fleet_deployment(
        deployment_id="deployment_id",
    )

    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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Get a configuration deployment by ID returns "OK" response

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

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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// Get a configuration deployment by ID 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.GetFleetDeployment", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewFleetAutomationApi(apiClient)
	resp, r, err := api.GetFleetDeployment(ctx, "deployment_id", *datadogV2.NewGetFleetDeploymentOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `FleetAutomationApi.GetFleetDeployment`:\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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// Get a configuration deployment by ID returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.FleetAutomationApi;
import com.datadog.api.client.v2.model.FleetDeploymentResponse;

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

    try {
      FleetDeploymentResponse result = apiInstance.getFleetDeployment("abc-def-ghi");
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling FleetAutomationApi#getFleetDeployment");
      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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// Get a configuration deployment by ID returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_fleet_automation::FleetAutomationAPI;
use datadog_api_client::datadogV2::api_fleet_automation::GetFleetDeploymentOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.GetFleetDeployment", true);
    let api = FleetAutomationAPI::with_config(configuration);
    let resp = api
        .get_fleet_deployment(
            "deployment_id".to_string(),
            GetFleetDeploymentOptionalParams::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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Get a configuration deployment by ID returns "OK" response
 */

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

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

const params: v2.FleetAutomationApiGetFleetDeploymentRequest = {
  deploymentId: "deployment_id",
};

apiInstance
  .getFleetDeployment(params)
  .then((data: v2.FleetDeploymentResponse) => {
    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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"