# Recurring maintenance windows

If the same maintenance happens on a regular schedule - a weekly deploy slot, a nightly backup that takes a service
offline - create one **weekly** window instead of a new window each time. It repeats on the days you choose, at the
same time of day, covering the same monitors with the same suppression.

Weekly is the only repeating schedule. There is no daily or monthly type: for "every night", choose all seven days;
for a monthly slot, create one-time windows.

## Settings reference

| Setting (UI label) | API field | Type / allowed values | Default | What it does for you |
|---|---|---|---|---|
| **Repeat** | `recurrence` | **Weekly** = `{"weekDays": [...]}`; **One time** = absent or `null` | One time | Makes the window repeat. The editor locks it after the window is created; the API can still set it or clear it with `recurrence: null`. |
| **Days of week** | `recurrence.weekDays` | `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday` (case-insensitive); at least one | Monday to Friday in the editor | The days an occurrence starts on. |
| **From** / **To** (**Window time (per occurrence)**) | `from` + `to`, or `from` + `durationSec` | Unix seconds / seconds | - | The time of day each occurrence starts and how long it lasts. `from` also sets the date the schedule begins. |
| **Time zone** | `timezone` | IANA zone id, e.g. `America/New_York` | `UTC` | The wall clock the days and times are read in. |

Every other field (name, monitors, alerts and stats, status page display) works as for a one-time window - see
[Create a maintenance window](/maintenance/create/).

## Set it up in the app

1. Open **Maintenance** in the sidebar and click **Add**.
2. Enter a **Short description**, for example "Weekly deploy slot".
3. Under **Schedule**, set **Repeat** to **Weekly**.
4. Tick the **Days of week**.
5. Set **From** and **To** - the time of day each occurrence starts and ends. If **To** is earlier than **From**, the
   occurrence runs past midnight into the next day: 22:00 to 03:00 is a five-hour night window starting on each
   chosen day.
6. Choose the **Time zone**.
7. Pick the **Affected Monitors** and their **Alerts** / **Stats** tiles, then **Save**.

## Do it with the API or MCP

`POST /maintenance` with a `recurrence` object:

```json
{
  "name": "Weekly deploy slot",
  "from": 1790056800,
  "durationSec": 3600,
  "timezone": "Europe/London",
  "recurrence": { "weekDays": ["Tuesday", "Thursday"] },
  "monitorIds": ["MONITOR_ID"],
  "suppress": { "alerts": true, "stats": true }
}
```

`from` is the first occurrence's start instant; its time of day in `timezone` is the time every occurrence starts.

With MCP, pass `weekDays` to `create_maintenance`, for example `weekDays: "Saturday,Sunday"`.

To change the days on an existing weekly window, `PATCH /maintenance/{id}` with a new `recurrence.weekDays` array. An
empty `weekDays` array is refused.

## How weekly windows behave

- **Local time is kept across daylight saving.** A window set for 02:00 in `Europe/Berlin` starts at 02:00 Berlin
  time in both summer and winter; it does not drift by an hour.
- **The state never becomes "finished".** A weekly window reads `scheduled` between occurrences and `active` during
  one; it keeps recurring until you pause (`enabled: false`) or delete it.
- **Status pages show upcoming occurrences.** With **Show on status page** on, each occurrence in the next 7 days
  appears on your status pages as planned maintenance, and past occurrences in the last 90 days are drawn in blue on
  the uptime bars. See [Show maintenance on your status page](/maintenance/status-page-display/).
- **The list groups it under RECURRING** and the **Next 7 days** strip draws its occurrences with a dashed purple bar.
- **The monitor list is fixed.** Every occurrence covers the monitors saved on the window. It cannot be scoped by
  tag, so a new monitor with the same tag is not covered until you add it (`PATCH /maintenance/{id}` with the full
  `monitorIds` list). See [Cover every monitor with a tag](/maintenance/create/#cover-every-monitor-with-a-tag).

:::caution[The repeat type is fixed at creation]
In the editor, whether a window is one-time or weekly is locked once it is saved ("Locked after creation"). To
switch in the app, delete the window and create a new one. Through the API, `PATCH /maintenance/{id}` with
`"recurrence": null` turns a weekly window into a one-time one, and a `recurrence` object does the reverse.
:::

## Related

- [Create a maintenance window](/maintenance/create/)
- [What a maintenance window is](/maintenance/overview/)
- [What a window suppresses](/maintenance/what-it-suppresses/)