Update a schedule

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

PATCH https://api.ap1.datadoghq.com/api/unstable/fleet/schedules/{id}https://api.ap2.datadoghq.com/api/unstable/fleet/schedules/{id}https://api.datadoghq.eu/api/unstable/fleet/schedules/{id}https://api.ddog-gov.com/api/unstable/fleet/schedules/{id}https://api.us2.ddog-gov.com/api/unstable/fleet/schedules/{id}https://api.datadoghq.com/api/unstable/fleet/schedules/{id}https://api.us3.datadoghq.com/api/unstable/fleet/schedules/{id}https://api.us5.datadoghq.com/api/unstable/fleet/schedules/{id}

Overview

Partially update a schedule by providing only the fields you want to change.

This endpoint allows you to modify specific attributes of a schedule without affecting other fields. Common use cases include:

  • Changing the schedule status between active and inactive
  • Updating the maintenance window times
  • Modifying the filter query to target different hosts
  • Adjusting the version strategy

Only include the fields you want to update in the request body. All fields are optional in a PATCH request.

This endpoint requires the agent_upgrade_write permission.

Arguments

Path Parameters

Name

Type

Description

id [required]

string

The unique identifier of the schedule to update.

Request

Body Data (required)

Request payload containing the fields to update.

Expand All

Field

Type

Description

data [required]

object

Data for partially updating a schedule.

attributes

object

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"
  }
}

Response

OK

Response containing a single schedule.

Expand All

Field

Type

Description

data

object

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"
  }
}

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

                  ## Change maintenance window time
# 

# Path parameters
export id="abc-def-ghi-123"
# Curl command
curl -X PATCH "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/schedules/${id}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "rule": { "days_of_week": [ "Mon", "Wed", "Fri" ], "maintenance_window_duration": 240, "start_maintenance_window": "03:00", "timezone": "America/New_York" } }, "type": "schedule" } } EOF
## default #
# Path parameters
export id="abc-def-ghi-123"
# Curl command
curl -X PATCH "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/schedules/${id}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "status": "inactive" }, "type": "schedule" } } EOF
## Pause a schedule #
# Path parameters
export id="abc-def-ghi-123"
# Curl command
curl -X PATCH "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/schedules/${id}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "status": "inactive" }, "type": "schedule" } } EOF
## Update target hosts query #
# Path parameters
export id="abc-def-ghi-123"
# Curl command
curl -X PATCH "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/schedules/${id}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "query": "env:prod AND service:api" }, "type": "schedule" } } EOF
"""
Update a schedule returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.fleet_automation_api import FleetAutomationApi
from datadog_api_client.v2.model.fleet_schedule_patch import FleetSchedulePatch
from datadog_api_client.v2.model.fleet_schedule_patch_attributes import FleetSchedulePatchAttributes
from datadog_api_client.v2.model.fleet_schedule_patch_request import FleetSchedulePatchRequest
from datadog_api_client.v2.model.fleet_schedule_recurrence_rule import FleetScheduleRecurrenceRule
from datadog_api_client.v2.model.fleet_schedule_resource_type import FleetScheduleResourceType
from datadog_api_client.v2.model.fleet_schedule_status import FleetScheduleStatus

body = FleetSchedulePatchRequest(
    data=FleetSchedulePatch(
        attributes=FleetSchedulePatchAttributes(
            name="Weekly Production Agent Updates",
            query="env:prod AND service:web",
            rule=FleetScheduleRecurrenceRule(
                days_of_week=[
                    "Mon",
                    "Wed",
                    "Fri",
                ],
                maintenance_window_duration=1200,
                start_maintenance_window="02:00",
                timezone="America/New_York",
            ),
            status=FleetScheduleStatus.ACTIVE,
            version_to_latest=0,
        ),
        type=FleetScheduleResourceType.SCHEDULE,
    ),
)

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

    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"
# Update a schedule returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.update_fleet_schedule".to_sym] = true
end
api_instance = DatadogAPIClient::V2::FleetAutomationAPI.new

body = DatadogAPIClient::V2::FleetSchedulePatchRequest.new({
  data: DatadogAPIClient::V2::FleetSchedulePatch.new({
    attributes: DatadogAPIClient::V2::FleetSchedulePatchAttributes.new({
      name: "Weekly Production Agent Updates",
      query: "env:prod AND service:web",
      rule: DatadogAPIClient::V2::FleetScheduleRecurrenceRule.new({
        days_of_week: [
          "Mon",
          "Wed",
          "Fri",
        ],
        maintenance_window_duration: 1200,
        start_maintenance_window: "02:00",
        timezone: "America/New_York",
      }),
      status: DatadogAPIClient::V2::FleetScheduleStatus::ACTIVE,
      version_to_latest: 0,
    }),
    type: DatadogAPIClient::V2::FleetScheduleResourceType::SCHEDULE,
  }),
})
p api_instance.update_fleet_schedule("id", body)

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"
// Update a schedule 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() {
	body := datadogV2.FleetSchedulePatchRequest{
		Data: datadogV2.FleetSchedulePatch{
			Attributes: &datadogV2.FleetSchedulePatchAttributes{
				Name:  datadog.PtrString("Weekly Production Agent Updates"),
				Query: datadog.PtrString("env:prod AND service:web"),
				Rule: &datadogV2.FleetScheduleRecurrenceRule{
					DaysOfWeek: []string{
						"Mon",
						"Wed",
						"Fri",
					},
					MaintenanceWindowDuration: 1200,
					StartMaintenanceWindow:    "02:00",
					Timezone:                  "America/New_York",
				},
				Status:          datadogV2.FLEETSCHEDULESTATUS_ACTIVE.Ptr(),
				VersionToLatest: datadog.PtrInt64(0),
			},
			Type: datadogV2.FLEETSCHEDULERESOURCETYPE_SCHEDULE,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.UpdateFleetSchedule", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewFleetAutomationApi(apiClient)
	resp, r, err := api.UpdateFleetSchedule(ctx, "id", body)

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `FleetAutomationApi.UpdateFleetSchedule`:\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"
// Update a schedule 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.FleetSchedulePatch;
import com.datadog.api.client.v2.model.FleetSchedulePatchAttributes;
import com.datadog.api.client.v2.model.FleetSchedulePatchRequest;
import com.datadog.api.client.v2.model.FleetScheduleRecurrenceRule;
import com.datadog.api.client.v2.model.FleetScheduleResourceType;
import com.datadog.api.client.v2.model.FleetScheduleResponse;
import com.datadog.api.client.v2.model.FleetScheduleStatus;
import java.util.Arrays;

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

    FleetSchedulePatchRequest body =
        new FleetSchedulePatchRequest()
            .data(
                new FleetSchedulePatch()
                    .attributes(
                        new FleetSchedulePatchAttributes()
                            .name("Weekly Production Agent Updates")
                            .query("env:prod AND service:web")
                            .rule(
                                new FleetScheduleRecurrenceRule()
                                    .daysOfWeek(Arrays.asList("Mon", "Wed", "Fri"))
                                    .maintenanceWindowDuration(1200L)
                                    .startMaintenanceWindow("02:00")
                                    .timezone("America/New_York"))
                            .status(FleetScheduleStatus.ACTIVE)
                            .versionToLatest(0L))
                    .type(FleetScheduleResourceType.SCHEDULE));

    try {
      FleetScheduleResponse result = apiInstance.updateFleetSchedule("abc-def-ghi-123", body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling FleetAutomationApi#updateFleetSchedule");
      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"
// Update a schedule returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_fleet_automation::FleetAutomationAPI;
use datadog_api_client::datadogV2::model::FleetSchedulePatch;
use datadog_api_client::datadogV2::model::FleetSchedulePatchAttributes;
use datadog_api_client::datadogV2::model::FleetSchedulePatchRequest;
use datadog_api_client::datadogV2::model::FleetScheduleRecurrenceRule;
use datadog_api_client::datadogV2::model::FleetScheduleResourceType;
use datadog_api_client::datadogV2::model::FleetScheduleStatus;

#[tokio::main]
async fn main() {
    let body = FleetSchedulePatchRequest::new(
        FleetSchedulePatch::new(FleetScheduleResourceType::SCHEDULE).attributes(
            FleetSchedulePatchAttributes::new()
                .name("Weekly Production Agent Updates".to_string())
                .query("env:prod AND service:web".to_string())
                .rule(FleetScheduleRecurrenceRule::new(
                    vec!["Mon".to_string(), "Wed".to_string(), "Fri".to_string()],
                    1200,
                    "02:00".to_string(),
                    "America/New_York".to_string(),
                ))
                .status(FleetScheduleStatus::ACTIVE)
                .version_to_latest(0),
        ),
    );
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.UpdateFleetSchedule", true);
    let api = FleetAutomationAPI::with_config(configuration);
    let resp = api.update_fleet_schedule("id".to_string(), body).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
/**
 * Update a schedule returns "OK" response
 */

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

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

const params: v2.FleetAutomationApiUpdateFleetScheduleRequest = {
  body: {
    data: {
      attributes: {
        name: "Weekly Production Agent Updates",
        query: "env:prod AND service:web",
        rule: {
          daysOfWeek: ["Mon", "Wed", "Fri"],
          maintenanceWindowDuration: 1200,
          startMaintenanceWindow: "02:00",
          timezone: "America/New_York",
        },
        status: "active",
        versionToLatest: 0,
      },
      type: "schedule",
    },
  },
  id: "id",
};

apiInstance
  .updateFleetSchedule(params)
  .then((data: v2.FleetScheduleResponse) => {
    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"