Get a deployment by ID

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

Overview

Retrieve detailed information about a specific deployment, including its current status, configuration operations, and per-host execution status.

Returns a 404 if no deployment matches the given ID or if you do not have access to it.

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.

Response

OK

Response containing detailed information about a single deployment.

Expand All

Field

Type

Description

data [required]

object

Detailed information about a deployment.

attributes [required]

object

Attributes of a deployment detail response.

author

string

Handle of the user who triggered the deployment.

canceled_hosts

int64

Number of hosts on which the deployment was canceled.

config_operations

[object]

Ordered list of configuration file operations applied by this deployment. Absent for package deployments, which have no configuration file operations.

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.

duration_seconds

int64

Duration of the deployment in seconds, computed as finished_at - started_at. Zero if the deployment has not finished.

error_summary

string

Top-level error message for the deployment. Populated only when the deployment has failed.

estimated_finished_at

int64

Estimated completion time of the deployment as a Unix timestamp. Zero if not available.

failed_hosts

int64

Number of hosts on which the deployment failed.

high_level_status

string

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

hosts

[object]

Per-host status list for this deployment.

error

string

Error message if the deployment failed on this host.

hostname

string

Hostname of the agent.

running_step

string

Name of the step currently executing on this host.

status

string

Deployment status for this host (for example, "pending", "running", "succeeded", "failed").

status_details

string

Additional details about the current deployment status on this host.

versions

[object]

Package version details for 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.

is_scheduled

boolean

Whether this deployment was triggered by a schedule (schedule_id is non-empty).

query

string

Query used to filter and select target hosts for the deployment.

running_hosts

int64

Number of hosts on which the deployment is currently running.

schedule_id

string

Identifier of the schedule that triggered this deployment. Empty if triggered manually.

skipped_hosts

int64

Number of hosts that were skipped during the deployment.

succeeded_hosts

int64

Number of hosts on which the deployment succeeded.

target_versions

[string]

Distinct package versions targeted by this deployment, in first-seen order.

total_hosts

int64

Total number of hosts targeted by this deployment.

update_type

string

Type of update operation performed by this deployment (for example, "update_config_operations", "update_package").

id [required]

string

Unique identifier for the deployment.

type [required]

enum

The type of deployment resource. Allowed enum values: deployment

default: deployment

{
  "data": {
    "attributes": {
      "author": "carol@datadoghq.com",
      "canceled_hosts": 1,
      "config_operations": [
        {
          "file_op": "merge-patch",
          "file_path": "/datadog.yaml",
          "patch": {
            "apm_config": {
              "enabled": true
            },
            "log_level": "debug",
            "logs_enabled": true
          }
        }
      ],
      "duration_seconds": 3600,
      "error_summary": "A host failed to update",
      "estimated_finished_at": 1699999999,
      "failed_hosts": 1,
      "high_level_status": "running",
      "hosts": [
        {
          "error": "",
          "hostname": "web-01.example.com",
          "running_step": "applying_config",
          "status": "running",
          "status_details": "step 2/3",
          "versions": [
            {
              "current_version": "7.51.0",
              "initial_version": "7.51.0",
              "package_name": "datadog-agent",
              "target_version": "7.52.0"
            }
          ]
        }
      ],
      "is_scheduled": true,
      "query": "env:prod AND service:web",
      "running_hosts": 1,
      "schedule_id": "sched-789",
      "skipped_hosts": 1,
      "succeeded_hosts": 1,
      "target_versions": [
        "7.52.0"
      ],
      "total_hosts": 42,
      "update_type": "update_config_operations"
    },
    "id": "k7Q-3mX-p9Z",
    "type": "deployment"
  }
}

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="k7Q-3mX-p9Z"
# 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/fleet/deployments/${deployment_id}" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
Get a deployment by ID returns "OK" response
"""

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

# there is a valid "deployment" in the system
DEPLOYMENT_ID = environ["DEPLOYMENT_ID"]

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = FleetAutomationApi(api_client)
    response = api_instance.get_fleet_deployment_v2(
        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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Get a deployment by ID returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::FleetAutomationAPI.new

# there is a valid "deployment" in the system
DEPLOYMENT_ID = ENV["DEPLOYMENT_ID"]
p api_instance.get_fleet_deployment_v2(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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// Get a 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() {
	// there is a valid "deployment" in the system
	DeploymentID := os.Getenv("DEPLOYMENT_ID")

	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewFleetAutomationApi(apiClient)
	resp, r, err := api.GetFleetDeploymentV2(ctx, DeploymentID)

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `FleetAutomationApi.GetFleetDeploymentV2`:\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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// Get a 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.FleetDeploymentV2DetailResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    FleetAutomationApi apiInstance = new FleetAutomationApi(defaultClient);

    // there is a valid "deployment" in the system
    String DEPLOYMENT_ID = System.getenv("DEPLOYMENT_ID");

    try {
      FleetDeploymentV2DetailResponse result = apiInstance.getFleetDeploymentV2(DEPLOYMENT_ID);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling FleetAutomationApi#getFleetDeploymentV2");
      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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// Get a deployment by ID returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_fleet_automation::FleetAutomationAPI;

#[tokio::main]
async fn main() {
    // there is a valid "deployment" in the system
    let deployment_id = std::env::var("DEPLOYMENT_ID").unwrap();
    let configuration = datadog::Configuration::new();
    let api = FleetAutomationAPI::with_config(configuration);
    let resp = api.get_fleet_deployment_v2(deployment_id.clone()).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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Get a deployment by ID returns "OK" response
 */

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

const configuration = client.createConfiguration();
const apiInstance = new v2.FleetAutomationApi(configuration);

// there is a valid "deployment" in the system
const DEPLOYMENT_ID = process.env.DEPLOYMENT_ID as string;

const params: v2.FleetAutomationApiGetFleetDeploymentV2Request = {
  deploymentId: DEPLOYMENT_ID,
};

apiInstance
  .getFleetDeploymentV2(params)
  .then((data: v2.FleetDeploymentV2DetailResponse) => {
    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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"