Retrieve a list of all available Datadog Agent versions.
This endpoint returns the available Agent versions that can be deployed to your fleet.
These versions are used when creating deployments or configuring schedules for
automated Agent upgrades.
Retrieve a paginated list of all Datadog Agents.
This endpoint returns a paginated list of all Datadog Agents with support for pagination, sorting, and filtering.
Use the page_number and page_size query parameters to paginate through results.
This endpoint requires the hosts_read permission.
인수
쿼리 문자열
이름
유형
설명
page_number
integer
Page number for pagination (must be greater than 0).
page_size
integer
Number of results per page (must be greater than 0 and less than or equal to 100).
sort_attribute
string
Attribute to sort by.
sort_descending
boolean
Sort order (true for descending, false for ascending).
Response containing a paginated list of Datadog Agents.
Expand All
항목
유형
설명
data [required]
object
The response data containing status and agents array.
attributes [required]
object
agents
[object]
Array of agents matching the query criteria.
agent_version
string
The Datadog Agent version.
api_key_name
string
The API key name (if available and not redacted).
api_key_uuid
string
The API key UUID.
cloud_provider
string
The cloud provider where the agent is running.
cluster_name
string
Kubernetes cluster name (if applicable).
datadog_agent_key
string
The unique agent key identifier.
enabled_products
[string]
Datadog products enabled on the agent.
envs
[string]
Environments the agent is reporting from.
first_seen_at
int64
Timestamp when the agent was first seen.
hostname
string
The hostname of the agent.
ip_addresses
[string]
IP addresses of the agent.
is_single_step_instrumentation_enabled
boolean
Whether single-step instrumentation is enabled.
last_restart_at
int64
Timestamp of the last agent restart.
os
string
The operating system.
otel_collector_version
string
OpenTelemetry collector version (if applicable).
otel_collector_versions
[string]
List of OpenTelemetry collector versions (if applicable).
pod_name
string
Kubernetes pod name (if applicable).
remote_agent_management
string
Remote agent management status.
remote_config_status
string
Remote configuration status.
services
[string]
Services running on the agent.
tags
[object]
Tags associated with the agent.
key
string
value
string
team
string
Team associated with the agent.
id [required]
string
Status identifier.
type [required]
string
Resource type.
meta
object
Metadata for the list of agents response.
total_filtered_count
int64
Total number of agents matching the filter criteria across all pages.
{"data":{"attributes":{"agents":[{"agent_version":"7.50.0","api_key_name":"Production API Key","api_key_uuid":"a1b2c3d4-e5f6-4321-a123-123456789abc","cloud_provider":"aws","cluster_name":"string","datadog_agent_key":"my-agent-hostname","enabled_products":[],"envs":[],"first_seen_at":"integer","hostname":"my-hostname","ip_addresses":[],"is_single_step_instrumentation_enabled":false,"last_restart_at":"integer","os":"linux","otel_collector_version":"string","otel_collector_versions":[],"pod_name":"string","remote_agent_management":"enabled","remote_config_status":"connected","services":[],"tags":[{"key":"string","value":"string"}],"team":"string"}]},"id":"done","type":"status"},"meta":{"total_filtered_count":150}}
Response containing detailed information about a specific agent.
Expand All
항목
유형
설명
data [required]
object
Represents detailed information about a specific Datadog Agent.
attributes [required]
object
Attributes for agent information.
agent_infos
object
Detailed information about a Datadog Agent.
agent_version
string
The Datadog Agent version.
api_key_name
string
The API key name (if available and not redacted).
api_key_uuid
string
The API key UUID.
cloud_provider
string
The cloud provider where the agent is running.
cluster_name
string
Kubernetes cluster name (if applicable).
datadog_agent_key
string
The unique agent key identifier.
enabled_products
[string]
Datadog products enabled on the agent.
env
[string]
Environments the agent is reporting from.
first_seen_at
int64
Timestamp when the agent was first seen.
hostname
string
The hostname of the agent.
hostname_aliases
[string]
Alternative hostname list for the agent.
install_method_installer_version
string
The version of the installer used.
install_method_tool
string
The tool used to install the agent.
ip_addresses
[string]
IP addresses of the agent.
is_single_step_instrumentation_enabled
boolean
Whether single-step instrumentation is enabled.
last_restart_at
int64
Timestamp of the last agent restart.
os
string
The operating system.
os_version
string
The operating system version.
otel_collector_version
string
OpenTelemetry collector version (if applicable).
otel_collector_versions
[string]
List of OpenTelemetry collector versions (if applicable).
otel_collectors
[object]
OpenTelemetry collectors associated with the agent (if applicable).
pod_name
string
Kubernetes pod name (if applicable).
python_version
string
The Python version used by the agent.
region
[string]
Regions where the agent is running.
remote_agent_management
string
Remote agent management status.
remote_config_status
string
Remote configuration status.
services
[string]
Services running on the agent.
tags
[string]
Tags associated with the agent.
team
string
Team associated with the agent.
configuration_files
object
Configuration information organized by layers.
compiled_configuration
string
The final compiled configuration.
env_configuration
string
Configuration from environment variables.
file_configuration
string
Configuration from files.
parsed_configuration
string
Parsed configuration output.
remote_configuration
string
Remote configuration settings.
runtime_configuration
string
Runtime configuration.
detected_integrations
[object]
List of detected integrations.
escaped_name
string
Escaped integration name.
prefix
string
Integration prefix identifier.
integrations
object
Integrations organized by their status.
configuration_files
[object]
Configuration files for integrations.
file_content
string
The raw content of the configuration file.
file_path
string
Path to the configuration file.
filename
string
Name of the configuration file.
datadog_agent_key
string
The unique agent key identifier.
error_integrations
[object]
Integrations with errors.
data_type
string
Type of data collected (metrics, logs).
error_messages
[string]
Error messages if the integration has issues.
init_config
string
Initialization configuration (YAML format).
instance_config
string
Instance-specific configuration (YAML format).
is_custom_check
boolean
Whether this is a custom integration.
log_config
string
Log collection configuration (YAML format).
name
string
Name of the integration instance.
source_index
int64
Index in the configuration file.
source_path
string
Path to the configuration file.
type
string
Integration type.
missing_integrations
[object]
Detected but not configured integrations.
escaped_name
string
Escaped integration name.
prefix
string
Integration prefix identifier.
warning_integrations
[object]
Integrations with warnings.
data_type
string
Type of data collected (metrics, logs).
error_messages
[string]
Error messages if the integration has issues.
init_config
string
Initialization configuration (YAML format).
instance_config
string
Instance-specific configuration (YAML format).
is_custom_check
boolean
Whether this is a custom integration.
log_config
string
Log collection configuration (YAML format).
name
string
Name of the integration instance.
source_index
int64
Index in the configuration file.
source_path
string
Path to the configuration file.
type
string
Integration type.
working_integrations
[object]
Integrations that are working correctly.
data_type
string
Type of data collected (metrics, logs).
error_messages
[string]
Error messages if the integration has issues.
init_config
string
Initialization configuration (YAML format).
instance_config
string
Instance-specific configuration (YAML format).
is_custom_check
boolean
Whether this is a custom integration.
log_config
string
Log collection configuration (YAML format).
name
string
Name of the integration instance.
source_index
int64
Index in the configuration file.
source_path
string
Path to the configuration file.
type
string
Integration type.
id [required]
string
The unique agent key identifier.
type [required]
enum
The type of Agent info resource.
Allowed enum values: datadog_agent_key
default: datadog_agent_key
{"data":{"attributes":{"agent_infos":{"agent_version":"7.50.0","api_key_name":"Production API Key","api_key_uuid":"a1b2c3d4-e5f6-4321-a123-123456789abc","cloud_provider":"aws","cluster_name":"string","datadog_agent_key":"my-agent-hostname","enabled_products":[],"env":[],"first_seen_at":"integer","hostname":"my-hostname","hostname_aliases":[],"install_method_installer_version":"1.2.3","install_method_tool":"chef","ip_addresses":[],"is_single_step_instrumentation_enabled":false,"last_restart_at":"integer","os":"linux","os_version":"Ubuntu 20.04","otel_collector_version":"string","otel_collector_versions":[],"otel_collectors":[],"pod_name":"string","python_version":"3.9.5","region":[],"remote_agent_management":"enabled","remote_config_status":"connected","services":[],"tags":[],"team":"string"},"configuration_files":{"compiled_configuration":"string","env_configuration":"string","file_configuration":"string","parsed_configuration":"string","remote_configuration":"string","runtime_configuration":"string"},"detected_integrations":[{"escaped_name":"postgresql","prefix":"postgres"}],"integrations":{"configuration_files":[{"file_content":"string","file_path":"/conf.d/postgres.d/postgres.yaml","filename":"postgres.yaml"}],"datadog_agent_key":"string","error_integrations":[{"data_type":"metrics","error_messages":[],"init_config":"string","instance_config":"string","is_custom_check":false,"log_config":"string","name":"string","source_index":"integer","source_path":"string","type":"postgres"}],"missing_integrations":[{"escaped_name":"postgresql","prefix":"postgres"}],"warning_integrations":[{"data_type":"metrics","error_messages":[],"init_config":"string","instance_config":"string","is_custom_check":false,"log_config":"string","name":"string","source_index":"integer","source_path":"string","type":"postgres"}],"working_integrations":[{"data_type":"metrics","error_messages":[],"init_config":"string","instance_config":"string","is_custom_check":false,"log_config":"string","name":"string","source_index":"integer","source_path":"string","type":"postgres"}]}},"id":"my-agent-hostname","type":"datadog_agent_key"}}
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.
인수
쿼리 문자열
이름
유형
설명
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
항목
유형
설명
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").
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 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","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":{"page":{"total_count":25}}}
Create a new deployment to apply configuration changes
to a fleet of hosts matching the specified filter query.
This endpoint supports two types of configuration operations:
merge-patch: Merges the provided patch data with the existing configuration file,
creating the file if it doesn’t exist
delete: Removes the specified configuration file from the target hosts
The deployment is created and started automatically. You can specify multiple configuration
operations that will be executed in order on each target host. Use the filter query to target
specific hosts using the Datadog query syntax.
This endpoint requires
all
of the following permissions:
agent_upgrade_write
fleet_policies_write
요청
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").
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}}}
Data for creating a new package upgrade deployment.
attributes [required]
object
Attributes for creating a new package upgrade deployment.
filter_query
string
Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.
target_packages [required]
[object]
List of packages and their target versions to deploy to the selected hosts.
name [required]
string
The name of the package to deploy.
version [required]
string
The target version of the package to deploy.
type [required]
enum
The type of deployment resource.
Allowed enum values: deployment
default: deployment
{"data":{"attributes":{"filter_query":"env:prod AND service:web","target_packages":[{"name":"datadog-agent","version":"7.52.0"}]},"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").
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}}}
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.
인수
경로 파라미터
이름
유형
설명
deployment_id [required]
string
The unique identifier of the deployment to retrieve.
쿼리 문자열
이름
유형
설명
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.
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}}}
Cancel an active deployment and stop all pending operations.
When you cancel a deployment:
All pending operations on hosts that haven’t started yet are stopped
Operations currently in progress on hosts may complete or be interrupted, depending on their current state
Configuration changes or package upgrades already applied to hosts are not rolled back
After cancellation, you can view the final state of the deployment using the GET endpoint to see which hosts
were successfully updated before the cancellation.
This endpoint requires
all
of the following permissions:
agent_upgrade_write
fleet_policies_write
인수
경로 파라미터
이름
유형
설명
deployment_id [required]
string
The unique identifier of the deployment to cancel.
Retrieve a list of all schedules for automated fleet deployments.
Schedules allow you to automate package upgrades by defining maintenance windows
and recurrence rules. Each schedule automatically creates deployments based on its
configuration.
Unix timestamp (seconds since epoch) when the schedule was created.
created_by
string
User handle of the person who created the schedule.
name
string
Human-readable name for the schedule.
query
string
Query used to filter and select target hosts for scheduled deployments. Uses the Datadog query syntax.
rule
object
Defines the recurrence pattern for the schedule. Specifies when deployments should be
automatically triggered based on maintenance windows.
days_of_week [required]
[string]
List of days of the week when the schedule should trigger. Valid values are:
"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun".
maintenance_window_duration [required]
int64
Duration of the maintenance window in minutes.
start_maintenance_window [required]
string
Start time of the maintenance window in 24-hour clock format (HH:MM).
Deployments will be triggered at this time on the specified days.
timezone [required]
string
Timezone for the schedule in IANA Time Zone Database format (e.g., "America/New_York", "UTC").
status
enum
The status of the schedule.
active: The schedule is active and will create deployments according to its recurrence rule.
inactive: The schedule is inactive and will not create any deployments.
Allowed enum values: active,inactive
updated_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was last updated.
updated_by
string
User handle of the person who last updated the schedule.
version_to_latest
int64
Number of major versions behind the latest to target for upgrades.
0: Always upgrade to the latest version
1: Upgrade to latest minus 1 major version
2: Upgrade to latest minus 2 major versions
Maximum value is 2.
id [required]
string
Unique identifier for the schedule.
type [required]
enum
The type of schedule resource.
Allowed enum values: schedule
default: schedule
{"data":[{"attributes":{"created_at_unix":1699999999,"created_by":"user@example.com","name":"Weekly Production Agent Updates","query":"env:prod AND service:web","rule":{"days_of_week":["Mon","Wed","Fri"],"maintenance_window_duration":1200,"start_maintenance_window":"02:00","timezone":"America/New_York"},"status":"active","updated_at_unix":1699999999,"updated_by":"user@example.com","version_to_latest":0},"id":"abc-def-ghi-123","type":"schedule"}]}
Create a new schedule for automated package upgrades.
Schedules define when and how often to automatically deploy package upgrades to a fleet
of hosts. Each schedule includes:
A filter query to select target hosts
A recurrence rule defining maintenance windows
A version strategy (e.g., always latest, or N versions behind latest)
When the schedule triggers during a maintenance window, it automatically creates a
deployment that upgrades the Datadog Agent to the specified version on all matching hosts.
This endpoint requires the agent_upgrade_write permission.
Query used to filter and select target hosts for scheduled deployments. Uses the Datadog query syntax.
rule [required]
object
Defines the recurrence pattern for the schedule. Specifies when deployments should be
automatically triggered based on maintenance windows.
days_of_week [required]
[string]
List of days of the week when the schedule should trigger. Valid values are:
"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun".
maintenance_window_duration [required]
int64
Duration of the maintenance window in minutes.
start_maintenance_window [required]
string
Start time of the maintenance window in 24-hour clock format (HH:MM).
Deployments will be triggered at this time on the specified days.
timezone [required]
string
Timezone for the schedule in IANA Time Zone Database format (e.g., "America/New_York", "UTC").
status
enum
The status of the schedule.
active: The schedule is active and will create deployments according to its recurrence rule.
inactive: The schedule is inactive and will not create any deployments.
Allowed enum values: active,inactive
version_to_latest
int64
Number of major versions behind the latest to target for upgrades.
0: Always upgrade to the latest version (default)
1: Upgrade to latest minus 1 major version
2: Upgrade to latest minus 2 major versions
Maximum value is 2.
type [required]
enum
The type of schedule resource.
Allowed enum values: schedule
default: schedule
{"data":{"attributes":{"name":"Weekly Production Agent Updates","query":"env:prod AND service:web","rule":{"days_of_week":["Mon","Wed","Fri"],"maintenance_window_duration":1200,"start_maintenance_window":"02:00","timezone":"America/New_York"},"status":"active","version_to_latest":0},"type":"schedule"}}
A schedule that automatically creates deployments based on a recurrence rule.
attributes [required]
object
Attributes of a schedule in the response.
created_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was created.
created_by
string
User handle of the person who created the schedule.
name
string
Human-readable name for the schedule.
query
string
Query used to filter and select target hosts for scheduled deployments. Uses the Datadog query syntax.
rule
object
Defines the recurrence pattern for the schedule. Specifies when deployments should be
automatically triggered based on maintenance windows.
days_of_week [required]
[string]
List of days of the week when the schedule should trigger. Valid values are:
"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun".
maintenance_window_duration [required]
int64
Duration of the maintenance window in minutes.
start_maintenance_window [required]
string
Start time of the maintenance window in 24-hour clock format (HH:MM).
Deployments will be triggered at this time on the specified days.
timezone [required]
string
Timezone for the schedule in IANA Time Zone Database format (e.g., "America/New_York", "UTC").
status
enum
The status of the schedule.
active: The schedule is active and will create deployments according to its recurrence rule.
inactive: The schedule is inactive and will not create any deployments.
Allowed enum values: active,inactive
updated_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was last updated.
updated_by
string
User handle of the person who last updated the schedule.
version_to_latest
int64
Number of major versions behind the latest to target for upgrades.
0: Always upgrade to the latest version
1: Upgrade to latest minus 1 major version
2: Upgrade to latest minus 2 major versions
Maximum value is 2.
id [required]
string
Unique identifier for the schedule.
type [required]
enum
The type of schedule resource.
Allowed enum values: schedule
default: schedule
{"data":{"attributes":{"created_at_unix":1699999999,"created_by":"user@example.com","name":"Weekly Production Agent Updates","query":"env:prod AND service:web","rule":{"days_of_week":["Mon","Wed","Fri"],"maintenance_window_duration":1200,"start_maintenance_window":"02:00","timezone":"America/New_York"},"status":"active","updated_at_unix":1699999999,"updated_by":"user@example.com","version_to_latest":0},"id":"abc-def-ghi-123","type":"schedule"}}
A schedule that automatically creates deployments based on a recurrence rule.
attributes [required]
object
Attributes of a schedule in the response.
created_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was created.
created_by
string
User handle of the person who created the schedule.
name
string
Human-readable name for the schedule.
query
string
Query used to filter and select target hosts for scheduled deployments. Uses the Datadog query syntax.
rule
object
Defines the recurrence pattern for the schedule. Specifies when deployments should be
automatically triggered based on maintenance windows.
days_of_week [required]
[string]
List of days of the week when the schedule should trigger. Valid values are:
"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun".
maintenance_window_duration [required]
int64
Duration of the maintenance window in minutes.
start_maintenance_window [required]
string
Start time of the maintenance window in 24-hour clock format (HH:MM).
Deployments will be triggered at this time on the specified days.
timezone [required]
string
Timezone for the schedule in IANA Time Zone Database format (e.g., "America/New_York", "UTC").
status
enum
The status of the schedule.
active: The schedule is active and will create deployments according to its recurrence rule.
inactive: The schedule is inactive and will not create any deployments.
Allowed enum values: active,inactive
updated_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was last updated.
updated_by
string
User handle of the person who last updated the schedule.
version_to_latest
int64
Number of major versions behind the latest to target for upgrades.
0: Always upgrade to the latest version
1: Upgrade to latest minus 1 major version
2: Upgrade to latest minus 2 major versions
Maximum value is 2.
id [required]
string
Unique identifier for the schedule.
type [required]
enum
The type of schedule resource.
Allowed enum values: schedule
default: schedule
{"data":{"attributes":{"created_at_unix":1699999999,"created_by":"user@example.com","name":"Weekly Production Agent Updates","query":"env:prod AND service:web","rule":{"days_of_week":["Mon","Wed","Fri"],"maintenance_window_duration":1200,"start_maintenance_window":"02:00","timezone":"America/New_York"},"status":"active","updated_at_unix":1699999999,"updated_by":"user@example.com","version_to_latest":0},"id":"abc-def-ghi-123","type":"schedule"}}
Attributes for partially updating a schedule. All fields are optional.
name
string
Human-readable name for the schedule.
query
string
Query used to filter and select target hosts for scheduled deployments. Uses the Datadog query syntax.
rule
object
Defines the recurrence pattern for the schedule. Specifies when deployments should be
automatically triggered based on maintenance windows.
days_of_week [required]
[string]
List of days of the week when the schedule should trigger. Valid values are:
"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun".
maintenance_window_duration [required]
int64
Duration of the maintenance window in minutes.
start_maintenance_window [required]
string
Start time of the maintenance window in 24-hour clock format (HH:MM).
Deployments will be triggered at this time on the specified days.
timezone [required]
string
Timezone for the schedule in IANA Time Zone Database format (e.g., "America/New_York", "UTC").
status
enum
The status of the schedule.
active: The schedule is active and will create deployments according to its recurrence rule.
inactive: The schedule is inactive and will not create any deployments.
Allowed enum values: active,inactive
version_to_latest
int64
Number of major versions behind the latest to target for upgrades.
0: Always upgrade to the latest version
1: Upgrade to latest minus 1 major version
2: Upgrade to latest minus 2 major versions
Maximum value is 2.
type [required]
enum
The type of schedule resource.
Allowed enum values: schedule
default: schedule
{"data":{"attributes":{"name":"Weekly Production Agent Updates","query":"env:prod AND service:web","rule":{"days_of_week":["Mon","Wed","Fri"],"maintenance_window_duration":1200,"start_maintenance_window":"02:00","timezone":"America/New_York"},"status":"active","version_to_latest":0},"type":"schedule"}}
A schedule that automatically creates deployments based on a recurrence rule.
attributes [required]
object
Attributes of a schedule in the response.
created_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was created.
created_by
string
User handle of the person who created the schedule.
name
string
Human-readable name for the schedule.
query
string
Query used to filter and select target hosts for scheduled deployments. Uses the Datadog query syntax.
rule
object
Defines the recurrence pattern for the schedule. Specifies when deployments should be
automatically triggered based on maintenance windows.
days_of_week [required]
[string]
List of days of the week when the schedule should trigger. Valid values are:
"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun".
maintenance_window_duration [required]
int64
Duration of the maintenance window in minutes.
start_maintenance_window [required]
string
Start time of the maintenance window in 24-hour clock format (HH:MM).
Deployments will be triggered at this time on the specified days.
timezone [required]
string
Timezone for the schedule in IANA Time Zone Database format (e.g., "America/New_York", "UTC").
status
enum
The status of the schedule.
active: The schedule is active and will create deployments according to its recurrence rule.
inactive: The schedule is inactive and will not create any deployments.
Allowed enum values: active,inactive
updated_at_unix
int64
Unix timestamp (seconds since epoch) when the schedule was last updated.
updated_by
string
User handle of the person who last updated the schedule.
version_to_latest
int64
Number of major versions behind the latest to target for upgrades.
0: Always upgrade to the latest version
1: Upgrade to latest minus 1 major version
2: Upgrade to latest minus 2 major versions
Maximum value is 2.
id [required]
string
Unique identifier for the schedule.
type [required]
enum
The type of schedule resource.
Allowed enum values: schedule
default: schedule
{"data":{"attributes":{"created_at_unix":1699999999,"created_by":"user@example.com","name":"Weekly Production Agent Updates","query":"env:prod AND service:web","rule":{"days_of_week":["Mon","Wed","Fri"],"maintenance_window_duration":1200,"start_maintenance_window":"02:00","timezone":"America/New_York"},"status":"active","updated_at_unix":1699999999,"updated_by":"user@example.com","version_to_latest":0},"id":"abc-def-ghi-123","type":"schedule"}}
Manually trigger a schedule to immediately create and start a deployment.
This endpoint allows you to manually initiate a deployment using the schedule’s
configuration, without waiting for the next scheduled maintenance window. This is
useful for:
Testing a schedule before it runs automatically
Performing an emergency update outside the regular maintenance window
Creating an ad-hoc deployment with the same settings as a schedule
The deployment is created immediately with:
The same filter query as the schedule
The package version determined by the schedule’s version strategy
All matching hosts as targets
The manually triggered deployment is independent of the schedule and does not
affect the schedule’s normal recurrence pattern.
This endpoint requires the agent_upgrade_write permission.
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}}}
