Manage automated deployments across your fleet of hosts.
Use these endpoints to create, retrieve, and cancel deployments
that apply configuration changes to multiple hosts at once.
Retrieve a list of all deployments for fleet automation.
Use the page_size and page_offset parameters to paginate results.
This endpoint requires the hosts_read permission.
Arguments
Query Strings
Name
Type
Description
page_size
integer
Number of deployments to return per page. Maximum value is 100.
page_offset
integer
Index of the first deployment to return. Use this with page_size to paginate through results.
Response containing a paginated list of deployments.
Expand All
Field
Type
Description
data [required]
[object]
Array of deployments matching the query criteria.
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").
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 the list of deployments, including pagination information.
page
object
Pagination details for the list of deployments.
total_count
int64
Total number of deployments available across all pages.
{"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","total_hosts":42},"id":"aeadc05e-98a8-11ec-ac2c-da7ad0900001","type":"deployment"}],"meta":{"page":{"total_count":25}}}
Create a new deployment to apply configuration changes
to a fleet of hosts matching the specified filter query.
This endpoint requires
all
of the following permissions:
agent_upgrade_write
fleet_policies_write
Request
Body Data (required)
Request payload containing the deployment details.
Attributes for creating a new configuration deployment.
config_operations [required]
[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.
filter_query
string
Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.
type [required]
enum
The type of deployment resource.
Allowed enum values: deployment
default: deployment
{"data":{"attributes":{"config_operations":[{"file_op":"merge-patch","file_path":"/datadog.yaml","patch":{"apm_config":{"enabled":true},"log_level":"debug","logs_enabled":true}}],"filter_query":"env:prod AND service:web"},"type":"deployment"}}
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").
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
{"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","total_hosts":42},"id":"aeadc05e-98a8-11ec-ac2c-da7ad0900001","type":"deployment"}}
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").
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
{"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","total_hosts":42},"id":"aeadc05e-98a8-11ec-ac2c-da7ad0900001","type":"deployment"}}
Cancel this deployment and stop all associated operations.
If a workflow is currently running for this deployment, it is canceled immediately.
Changes already applied to hosts are not rolled back.
This endpoint requires
all
of the following permissions:
agent_upgrade_write
fleet_policies_write
Arguments
Path Parameters
Name
Type
Description
deployment_id [required]
string
The unique identifier of the deployment to cancel.
