--- title: Manage monitor downtimes source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/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](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/monitor-downtimes-disable-monitoring-during-scheduled-maintenance-times/). > #### 💡 TIP > > For timezone values, refer to the [tz database of time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). For example, use `America/Los_Angeles` for Pacific Time. ## Create a one-time monitor downtime [#create-once-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](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) 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 ```graphql 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 [#create-daily-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](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) 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 ```graphql 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 [#create-weekly-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](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) 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 ```graphql 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 [#create-monthly-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](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) 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 ```graphql 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 [#update-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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors) of the existing monitor downtime to update. | | `name` | String | No | Updated name for the downtime. | | `monitorGuids` | Array | No | Updated list of monitor [GUIDs](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitors). | | `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 ```graphql 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 [#delete-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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitor-downtimes) of the monitor downtime to delete. | ### Sample request ```graphql mutation { syntheticsDeleteMonitorDowntime( guid: "DOWNTIME_ENTITY_GUID" ) { guid } } ``` ## Query monitor downtimes [#query-monitor-downtimes] Use NerdGraph to retrieve downtime schedules, configurations, and metadata. For more information, refer to: - [Query monitor downtimes](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-monitor-downtimes) - Get all scheduled monitor downtimes with their configurations. To view complete list of query examples, refer to the [Query synthetics data](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data) document.