---
title: "Upgrade hosts"
method: POST
path: "/api/v2/fleet/deployments/upgrade"
tags: ["Fleet Automation"]
---

# Upgrade hosts

`POST /api/v2/fleet/deployments/upgrade`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/fleet/deployments/upgrade`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/fleet/deployments/upgrade/post.ts> (a function with typed inputs; its response is checked against the schema)

Create and immediately start a new package upgrade
on hosts matching the specified filter query.

This endpoint allows you to upgrade the Datadog Agent to a specific version
on hosts matching the specified filter query.

The deployment is created and started automatically. The system:
1. Identifies all hosts matching the filter query.
2. Validates that the specified version is available.
3. Begins rolling out the package upgrade to the target hosts.

Returns a 400 if `filter_query` or `target_packages` is missing, a target package is missing a name or version, or the filter query does not match any host eligible for the upgrade. Returns a 409 if a conflicting upgrade is already running on one or more target hosts.

## Request body

- FleetDeploymentPackageUpgradeV2CreateRequest: Request payload for creating a new v2 package upgrade deployment.
  - `data` FleetDeploymentPackageUpgradeV2Create, required: Data for creating a new v2 package upgrade deployment.
    - `attributes` FleetDeploymentPackageUpgradeV2Attributes, required: Attributes for creating a new v2 package upgrade deployment.
      - `filter_query` string, required: Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.
      - `target_packages` FleetDeploymentPackage[], required: List of packages and their target versions to deploy to the selected hosts.
        - `name` string, required: The name of the package to deploy.
        - `version` string, required: The target version of the package to deploy.
    - `type` 'deployment', required: The type of deployment resource.

## Response `201`

CREATED

- FleetDeploymentV2CreateResponse: Response containing the newly created deployment.
  - `data` FleetDeploymentV2, required: A deployment in the v2 API response.
    - `attributes` FleetDeploymentV2Attributes, required: Attributes of a deployment in the v2 API response.
      - `author` string: Handle of the user who triggered the deployment.
      - `config_operations` FleetDeploymentOperation[]: Ordered list of configuration file operations applied by this deployment. Absent for package deployments, which have no configuration file operations.
        - `file_op` 'merge-patch' | 'delete', required: 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.
        - `file_path` string, required: 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` integer: 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` integer: Estimated completion time of the deployment as a Unix timestamp. Zero if not available.
      - `finished_at` integer: Time the deployment finished as a Unix timestamp. Zero if not yet finished.
      - `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.
      - `schedule_id` string: Identifier of the schedule that triggered this deployment. Empty if triggered manually.
      - `started_at` integer: Time the deployment started as a Unix timestamp. Zero if not yet started.
      - `status` string: Current high-level status of the deployment (for example, "pending", "running", "completed", "failed").
      - `target_versions` string[]: Package versions targeted by this deployment.
      - `total_hosts` integer: 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` string, required: Unique identifier for the deployment.
    - `type` 'deployment', required: The type of deployment resource.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)