Manage monitor downtimes

Monitor downtimes let you schedule periods when your synthetic monitors stop running. This is useful during planned maintenance, deployments, or known outages when you don't want to receive alerts. You can create one-time downtimes or recurring schedules (daily, weekly, or monthly). This tutorial provides examples of how to use the NerdGraph API to programmatically manage monitor downtimes. To manage monitor downtimes using the UI, refer to Disable monitoring during scheduled maintenance times.

Tip

For timezone values, refer to the tz database of time zones. For example, use America/Los_Angeles for Pacific Time.

Create a one-time monitor downtime

You can create a one-time monitor downtime using the syntheticsCreateOnceMonitorDowntime mutation. Use this for planned maintenance or events that happen only once.

Input parameters

Parameter	Data Type	Is it Required?	Description
`accountId`	Integer	Yes	The New Relic account ID where the downtime will be created.
`name`	String	Yes	A descriptive name for the downtime period.
`monitorGuids`	Array	No	List of monitor GUIDs to include in the downtime. Leave empty to apply to all monitors.
`timezone`	String	Yes	The timezone for the downtime schedule (e.g., `America/New_York`).
`startTime`	String	Yes	When the downtime starts in `yyyy-MM-ddTHH:mm:ss` format.
`endTime`	String	Yes	When the downtime ends in `yyyy-MM-ddTHH:mm:ss` format.

Sample request

mutation {
  syntheticsCreateOnceMonitorDowntime(
    accountId: ACCOUNT_ID
    name: "MonitorDowntimeName"
    monitorGuids: ["OptionalMonitorEntityGuid", "OptionalMonitorEntityGuid"]
    timezone: "TIMEZONE"
    startTime: "yyyy-MM-ddTHH:mm:ss"
    endTime: "yyyy-MM-ddTHH:mm:ss"
  ) {
    guid
    accountId
    name
    monitorGuids
    timezone
    startTime
    endTime
  }
}

Create a daily recurring monitor downtime

You can create a daily recurring monitor downtime using the syntheticsCreateDailyMonitorDowntime mutation. Use this for regular maintenance windows that occur every day.

Input parameters

Parameter	Data Type	Is it Required?	Description
`accountId`	Integer	Yes	The New Relic account ID where the downtime will be created.
`name`	String	Yes	A descriptive name for the recurring downtime.
`monitorGuids`	Array	No	List of monitor GUIDs to include in the downtime.
`timezone`	String	Yes	The timezone for the downtime schedule.
`startTime`	String	Yes	Daily start time in `yyyy-MM-ddTHH:mm:ss` format.
`endTime`	String	Yes	Daily end time in `yyyy-MM-ddTHH:mm:ss` format.
`endRepeat`	Object	No	When to stop the recurring downtime. Use `onDate` for a specific date or `onRepeat` for number of occurrences.

Sample request

mutation {
  syntheticsCreateDailyMonitorDowntime(
    accountId: ACCOUNT_ID
    name: "MonitorDowntimeName"
    monitorGuids: [
      "OptionalMonitorEntityGuid"
      "AnotherOptionalMonitorEntityGuid"
    ]
    timezone: "TIMEZONE"
    startTime: "yyyy-MM-ddTHH:mm:ss"
    endTime: "yyyy-MM-ddTHH:mm:ss"
    endRepeat: { onDate: "yyyy-MM-ddTHH:mm:ss", onRepeat: 10 }
  ) {
    guid
    accountId
    name
    monitorGuids
    timezone
    startTime
    endTime
    endRepeat {
      onDate
      onRepeat
    }
  }
}

Create a weekly recurring monitor downtime

You can create a weekly recurring monitor downtime using the syntheticsCreateWeeklyMonitorDowntime mutation. Use this for maintenance windows that occur on specific days of the week.

Input parameters

Parameter	Data Type	Is it Required?	Description
`accountId`	Integer	Yes	The New Relic account ID where the downtime will be created.
`name`	String	Yes	A descriptive name for the weekly downtime.
`monitorGuids`	Array	No	List of monitor GUIDs to include in the downtime.
`timezone`	String	Yes	The timezone for the downtime schedule.
`startTime`	String	Yes	Weekly start time in `yyyy-MM-ddTHH:mm:ss` format.
`endTime`	String	Yes	Weekly end time in `yyyy-MM-ddTHH:mm:ss` format.
`maintenanceDays`	Array	Yes	Days of the week (e.g., `MONDAY`, `TUESDAY`, `WEDNESDAY`).
`endRepeat`	Object	No	When to stop the recurring downtime.

Sample request

mutation {
  syntheticsCreateWeeklyMonitorDowntime(
    accountId: ACCOUNT_ID
    name: "MonitorDowntimeName"
    monitorGuids: [
      "OptionalMonitorEntityGuid"
      "AnotherOptionalMonitorEntityGuid"
    ]
    timezone: "TIMEZONE"
    startTime: "yyyy-MM-ddTHH:mm:ss"
    endTime: "yyyy-MM-ddTHH:mm:ss"
    maintenanceDays: [MONDAY, WEDNESDAY, FRIDAY]
    endRepeat: { onDate: "yyyy-MM-ddTHH:mm:ss", onRepeat: 20 }
  ) {
    guid
    accountId
    name
    monitorGuids
    timezone
    startTime
    endTime
    maintenanceDays
    endRepeat {
      onDate
      onRepeat
    }
  }
}

Create a monthly recurring monitor downtime

You can create a monthly recurring monitor downtime using the syntheticsCreateMonthlyMonitorDowntime mutation. Use this for maintenance windows that occur on specific days each month.

Input parameters

Parameter	Data Type	Is it Required?	Description
`accountId`	Integer	Yes	The New Relic account ID where the downtime will be created.
`name`	String	Yes	A descriptive name for the monthly downtime.
`monitorGuids`	Array	No	List of monitor GUIDs to include in the downtime.
`timezone`	String	Yes	The timezone for the downtime schedule.
`startTime`	String	Yes	Monthly start time in `yyyy-MM-ddTHH:mm:ss` format.
`endTime`	String	Yes	Monthly end time in `yyyy-MM-ddTHH:mm:ss` format.
`frequency`	Object	Yes	Defines when in the month the downtime occurs. Use `daysOfWeek` for relative dates (e.g., first Monday) or `daysOfMonth` for specific dates (e.g., 15th of each month).
`endRepeat`	Object	No	When to stop the recurring downtime.

Sample request

mutation {
  syntheticsCreateMonthlyMonitorDowntime(
    accountId: ACCOUNT_ID
    name: "MonitorDowntimeName"
    monitorGuids: [
      "OptionalMonitorEntityGuid"
      "AnotherOptionalMonitorEntityGuid"
    ]
    timezone: "TIMEZONE"
    startTime: "yyyy-MM-ddTHH:mm:ss"
    endTime: "yyyy-MM-ddTHH:mm:ss"
    frequency: {
      daysOfWeek: { weekDay: MONDAY, ordinalDayOfMonth: FIRST }
      daysOfMonth: [15]
    }
    endRepeat: { onDate: "yyyy-MM-ddTHH:mm:ss", onRepeat: 12 }
  ) {
    guid
    accountId
    name
    monitorGuids
    timezone
    startTime
    endTime
    frequency {
      daysOfWeek {
        weekDay
        ordinalDayOfMonth
      }
      daysOfMonth
    }
    endRepeat {
      onDate
      onRepeat
    }
  }
}

Update a monitor downtime

You can update an existing monitor downtime using the syntheticsEditMonitorDowntime mutation. This allows you to modify any downtime type (once, daily, weekly, or monthly) using this single mutation.

Input parameters

Parameter	Data Type	Is it Required?	Description
`guid`	String	Yes	The GUID of the existing monitor downtime to update.
`name`	String	No	Updated name for the downtime.
`monitorGuids`	Array	No	Updated list of monitor GUIDs.
`once`	Object	No	Configuration for one-time downtime.
`daily`	Object	No	Configuration for daily recurring downtime.
`weekly`	Object	No	Configuration for weekly recurring downtime.
`monthly`	Object	No	Configuration for monthly recurring downtime.

Sample request

mutation {
  syntheticsEditMonitorDowntime(
    guid: "MonitorDowntimeEntityGuid"
    name: "MONITOR_DOWNTIME_NAME"
    monitorGuids: [
      "OptionalMonitorEntityGuid"
      "AnotherOptionalMonitorEntityGuid"
    ]
    once: {
      timezone: "TIMEZONE"
      startTime: "yyyy-MM-ddTHH:mm:ss"
      endTime: "yyyy-MM-ddTHH:mm:ss"
    }
    daily: {
      timezone: "TIMEZONE"
      startTime: "yyyy-MM-ddTHH:mm:ss"
      endTime: "yyyy-MM-ddTHH:mm:ss"
      endRepeat: { onDate: "yyyy-MM-ddTHH:mm:ss", onRepeat: 30 }
    }
    weekly: {
      timezone: "TIMEZONE"
      startTime: "yyyy-MM-ddTHH:mm:ss"
      endTime: "yyyy-MM-ddTHH:mm:ss"
      endRepeat: { onDate: "yyyy-MM-ddTHH:mm:ss", onRepeat: 20 }
      maintenanceDays: [MONDAY, WEDNESDAY]
    }
    monthly: {
      timezone: "TIMEZONE"
      startTime: "yyyy-MM-ddTHH:mm:ss"
      endTime: "yyyy-MM-ddTHH:mm:ss"
      endRepeat: { onDate: "yyyy-MM-ddTHH:mm:ss", onRepeat: 12 }
      frequency: {
        daysOfWeek: { weekDay: MONDAY, ordinalDayOfMonth: FIRST }
        daysOfMonth: [15]
      }
    }
  ) {
    guid
    accountId
    name
    monitorGuids
    timezone
    startTime
    endTime
    endRepeat {
      onDate
      onRepeat
    }
    maintenanceDays
    frequency {
      daysOfWeek {
        weekDay
        ordinalDayOfMonth
      }
      daysOfMonth
    }
  }
}

Delete a monitor downtime

You can delete a monitor downtime using the syntheticsDeleteMonitorDowntime mutation. Once deleted, the scheduled downtime will be removed and monitors will resume their normal schedule.

Input parameters

Parameter	Data Type	Is it Required?	Description
`guid`	String	Yes	The GUID of the monitor downtime to delete.

Sample request

mutation {
  syntheticsDeleteMonitorDowntime(guid: "DOWNTIME_ENTITY_GUID") {
    guid
  }
}

Tip

Create a one-time monitor downtime .css-21sua1{background:none;border:none;width:0;padding:0;}

Input parameters

Sample request

Create a daily recurring monitor downtime

Input parameters

Sample request

Create a weekly recurring monitor downtime

Input parameters

Sample request

Create a monthly recurring monitor downtime

Input parameters

Sample request

Update a monitor downtime

Input parameters

Sample request

Delete a monitor downtime

Input parameters

Sample request

Create a one-time monitor downtime