> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-simo-red-1015-maintenance-window-timezone.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MaintenanceWindow Construct

> Learn how to configure maintenance windows with the Checkly CLI.

<Tip>
  Learn more about Maintenance Windows in [the Maintenance Windows documentation](/communicate/maintenance-windows/overview).
</Tip>

Use Maintenance Windows to schedule planned maintenance periods that prevent your checks from running and triggering alerts during expected downtime.

<CodeGroup>
  ```ts One-Time Maintenance theme={null}
  import { MaintenanceWindow } from "checkly/constructs"

  new MaintenanceWindow("server-upgrade", {
    name: "Server Upgrade Maintenance",
    tags: ["production", "api"],
    startsAt: new Date("2025-02-15T02:00:00.000Z"),
    endsAt: new Date("2025-02-15T06:00:00.000Z"),
  })
  ```

  ```ts Recurring Maintenance theme={null}
  import { MaintenanceWindow } from "checkly/constructs"

  new MaintenanceWindow("weekly-backup", {
    name: "Weekly Database Backup",
    tags: ["database", "backup"],
    startsAt: new Date("2025-02-01T03:00:00.000Z"),
    endsAt: new Date("2025-02-01T04:00:00.000Z"),
    repeatInterval: 1,
    repeatUnit: "WEEK",
    repeatEndsAt: new Date("2025-12-31T23:59:59.000Z"),
  })
  ```
</CodeGroup>

## Configuration

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | `string` | ✅ | - | Name of the maintenance window |
| `startsAt` | `Date` | ✅ | - | Start date and time (ISO 8601 timestamp) |
| `endsAt` | `Date` | ✅ | - | End date and time (ISO 8601 timestamp) |
| `tags` | `string[]` | ❌ | `[]` | Tags that filter which checks are paused |
| `repeatInterval` | `number` | ❌ | - | Repeat interval from the first occurrence |
| `repeatUnit` | `string` | ❌ | - | Repeat strategy: `'DAY'` \| `'WEEK'` \| `'MONTH'` |
| `repeatEndsAt` | `Date` | ❌ | - | When to stop repeating (ISO 8601 timestamp) |
| `timezone` | `string` | ❌ | UTC | IANA time zone used to schedule recurring occurrences |
| `pauseAllChecks` | `boolean` | ❌ | `false` | Pause every check in the account, regardless of `tags` |
| `silenceAlertsTags` | `string[]` | ❌ | `[]` | Tags that filter which checks have their alerts silenced |
| `silenceAllAlerts` | `boolean` | ❌ | `false` | Silence alerts for every check in the account |

### `MaintenanceWindow` Options

<ResponseField name="name" type="string" required>
  A name for the maintenance window that will be displayed in the Checkly dashboard and used for identification.

  Usage:

  ```ts highlight={2} theme={null}
  new MaintenanceWindow("my-maintenance", {
    name: "Weekly Database Backup",
    /* More options... */
  })
  ```

  **Use cases**: Window identification, dashboard display, maintenance tracking.
</ResponseField>

<ResponseField name="tags" type="string[]">
  Tags that filter which checks are affected by this maintenance window. Checks with ANY of these tags will be paused during the maintenance period to avoid unnecessary alerts. Not needed when `pauseAllChecks` is `true`.

  **Usage:**

  ```ts highlight={3} theme={null}
  new MaintenanceWindow("my-maintenance", {
    name: "API Maintenance",
    tags: ["api", "backend"],
    /* More options... */
  })
  ```

  <Warning>
    Maintenance windows affect ALL checks that have ANY of the specified tags. Be specific with your tags to avoid affecting unintended checks.
  </Warning>

  **Use cases**: Service targeting, environment isolation, maintenance scope control.
</ResponseField>

<ResponseField name="startsAt" type="Date" required>
  Start date and time for the maintenance window in UTC (ISO 8601 timestamp).

  **Usage:**

  ```ts highlight={3} theme={null}
  new MaintenanceWindow("my-maintenance", {
    name: "Database Maintenance",
    startsAt: new Date("2025-02-15T02:00:00.000Z"), // 2 AM UTC
    /* More options... */
  })
  ```

  **Use cases**: Scheduled downtime, emergency maintenance, recurring maintenance timing.
</ResponseField>

<ResponseField name="endsAt" type="Date" required>
  End date and time for the maintenance window in UTC (ISO 8601 timestamp).

  **Usage:**

  ```ts highlight={4} theme={null}
  new MaintenanceWindow("my-maintenance", {
    name: "Database Maintenance",
    startsAt: new Date("2025-02-15T02:00:00.000Z"),
    endsAt: new Date("2025-02-15T06:00:00.000Z"), // 4-hour window
    /* More options... */
  })
  ```

  **Use cases**: Maintenance duration control, downtime limitation, schedule coordination.
</ResponseField>

<ResponseField name="repeatInterval" type="number">
  Repeat interval from the first occurrence. Used with `repeatUnit` to create recurring maintenance windows.

  **Usage:**

  ```ts highlight={3} theme={null}
  new MaintenanceWindow("recurring-maintenance", {
    name: "Weekly Maintenance",
    repeatInterval: 1, // Every 1 week
    repeatUnit: "WEEK",
    /* More options... */
  })
  ```

  **Use cases**: Regular maintenance scheduling, automated recurring downtime, consistent maintenance intervals.
</ResponseField>

<ResponseField name="repeatUnit" type="string">
  Repeat strategy that defines the time unit for recurring maintenance windows (`DAY` | `WEEK` | `MONTH`).

  **Usage:**

  ```ts highlight={4} theme={null}
  new MaintenanceWindow('recurring-maintenance', {
    name: "Bi-weekly Maintenance",
    repeatInterval: 2,
    repeatUnit: 'WEEK' // Every 2 weeks
    /* More options... */
  })
  ```

  **Examples:**

  <CodeGroup>
    ```ts Daily Maintenance theme={null}
    new MaintenanceWindow("daily-updates", {
      name: "Daily Database Sync",
      repeatInterval: 1,
      repeatUnit: "DAY",
      startsAt: new Date("2025-02-02T01:00:00.000Z"), // Every Sunday
      endsAt: new Date("2025-02-02T01:30:00.000Z"),
      tags: ["db-sync"],
    })
    ```

    ```ts Weekly Maintenance theme={null}
    new MaintenanceWindow("weekly-updates", {
      name: "Weekly System Updates",
      repeatInterval: 1,
      repeatUnit: "WEEK",
      startsAt: new Date("2025-02-02T01:00:00.000Z"), // Every Sunday
      endsAt: new Date("2025-02-02T02:30:00.000Z"),
      tags: ["updates"],
    })
    ```

    ```ts Monthly Maintenance theme={null}
    new MaintenanceWindow("monthly-db", {
      name: "Monthly Database Maintenance",
      repeatInterval: 1,
      repeatUnit: "MONTH",
      startsAt: new Date("2025-02-01T02:00:00.000Z"), // First of each month
      endsAt: new Date("2025-02-01T05:00:00.000Z"),
      tags: ["database"],
    })
    ```
  </CodeGroup>

  **Use cases**: Time-based recurrence patterns, maintenance scheduling consistency, automated repetition.
</ResponseField>

<ResponseField name="repeatEndsAt" type="Date">
  When to stop repeating the maintenance window (ISO 8601 timestamp in UTC). If not specified, the maintenance window will repeat indefinitely.

  **Usage:**

  ```ts highlight={5} theme={null}
  new MaintenanceWindow("limited-recurring", {
    name: "Limited Time Maintenance",
    repeatInterval: 1,
    repeatUnit: "WEEK",
    repeatEndsAt: new Date("2025-12-31T23:59:59.000Z"), // Stop at end of year
    /* More options... */
  })
  ```

  **Use cases**: Limited-time maintenance periods, project-based scheduling, planned end dates.
</ResponseField>

<ResponseField name="timezone" type="string">
  The named [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used to schedule recurring occurrences, for example `"America/New_York"`. Occurrences keep the same local time across daylight-saving changes; see [Timezones and daylight saving](/communicate/maintenance-windows/overview#timezones-and-daylight-saving). Editors suggest known zone names as you type.

  `startsAt` and `endsAt` stay absolute instants: the time zone does not reinterpret them, it only decides how later occurrences follow local time. UTC offsets such as `"+05:00"` or `"Etc/GMT+5"` are not accepted. Defaults to UTC.

  **Usage:**

  ```ts highlight={4} theme={null}
  new MaintenanceWindow("nightly-maintenance", {
    name: "Nightly Maintenance",
    tags: ["production"],
    timezone: "Europe/Berlin",
    startsAt: new Date("2025-02-15T02:00:00.000Z"), // 03:00 in Berlin
    endsAt: new Date("2025-02-15T03:00:00.000Z"),
    repeatInterval: 1,
    repeatUnit: "DAY",
  })
  ```

  <Warning>
    The CLI always sends the time zone on deploy. If you remove `timezone` from your code, or a time zone was set for the window in the Checkly UI, the next deploy resets the window to UTC. A time zone can't be changed while a maintenance is active, so a deploy that changes it during an active maintenance fails until the maintenance ends.
  </Warning>

  **Use cases**: Maintenance tied to local business hours, recurring windows that must survive daylight-saving changes.
</ResponseField>

<ResponseField name="pauseAllChecks" type="boolean" default="false">
  Pause every check in the account during the maintenance window, regardless of `tags`.

  **Usage:**

  ```ts highlight={3} theme={null}
  new MaintenanceWindow("platform-migration", {
    name: "Platform Migration",
    pauseAllChecks: true,
    /* More options... */
  })
  ```

  **Use cases**: Account-wide migrations, full platform downtime.
</ResponseField>

<ResponseField name="silenceAlertsTags" type="string[]">
  Tags that filter which checks have their alerts silenced during the maintenance window. Silenced checks keep running and collecting data, but alert channels aren't notified. Ignored when `silenceAllAlerts` is `true`.

  **Usage:**

  ```ts highlight={3} theme={null}
  new MaintenanceWindow("degraded-api", {
    name: "Expected API Degradation",
    silenceAlertsTags: ["api"],
    /* More options... */
  })
  ```

  **Use cases**: Keep monitoring during expected degradation without noisy alerts.
</ResponseField>

<ResponseField name="silenceAllAlerts" type="boolean" default="false">
  Silence alerts for every check in the account during the maintenance window, regardless of `silenceAlertsTags`. Checks keep running.

  **Usage:**

  ```ts highlight={3} theme={null}
  new MaintenanceWindow("quiet-period", {
    name: "Quiet Period",
    silenceAllAlerts: true,
    /* More options... */
  })
  ```

  **Use cases**: Account-wide alert silencing while monitoring continues.
</ResponseField>

## Examples

<Tabs>
  <Tab title="Database Maintenance">
    ```ts theme={null}
    new MaintenanceWindow("database-maintenance", {
      name: "Monthly Database Maintenance",
      tags: ["database", "production"],
      startsAt: new Date("2025-02-01T02:00:00.000Z"), // First Saturday of month at 2 AM UTC
      endsAt: new Date("2025-02-01T05:00:00.000Z"), // Ends at 5 AM UTC
      repeatInterval: 1,
      repeatUnit: "MONTH",
      repeatEndsAt: new Date("2025-12-31T23:59:59.000Z"), // Repeat for a year
    })
    ```
  </Tab>

  <Tab title="Weekly System Updates">
    ```ts theme={null}
    new MaintenanceWindow("system-updates", {
      name: "Weekly System Updates",
      tags: ["infrastructure", "updates"],
      startsAt: new Date("2025-02-02T01:00:00.000Z"), // Every Sunday at 1 AM UTC
      endsAt: new Date("2025-02-02T02:30:00.000Z"), // 1.5 hour window
      repeatInterval: 1,
      repeatUnit: "WEEK",
      repeatEndsAt: new Date("2025-06-01T00:00:00.000Z"), // Repeat until June
    })
    ```
  </Tab>

  <Tab title="Emergency Maintenance">
    ```ts theme={null}
    // For immediate one-time maintenance
    const now = new Date()
    const inOneHour = new Date(now.getTime() + 60 * 60 * 1000)
    const inFourHours = new Date(now.getTime() + 4 * 60 * 60 * 1000)

    new MaintenanceWindow("emergency-fix", {
      name: "Emergency Security Patch",
      tags: ["security", "critical"],
      startsAt: inOneHour, // Start in 1 hour
      endsAt: inFourHours, // End in 4 hours (no repeat)
    })
    ```
  </Tab>

  <Tab title="Service-Specific Maintenance">
    ```ts theme={null}
    // API service maintenance
    new MaintenanceWindow("api-maintenance", {
      name: "API Service Upgrade",
      tags: ["api", "backend"],
      startsAt: new Date("2025-02-20T03:00:00.000Z"),
      endsAt: new Date("2025-02-20T04:00:00.000Z"),
    })

    // Frontend deployment
    new MaintenanceWindow("frontend-deployment", {
      name: "Frontend Deployment",
      tags: ["frontend", "web"],
      startsAt: new Date("2025-02-20T04:30:00.000Z"),
      endsAt: new Date("2025-02-20T05:00:00.000Z"),
    })

    // Database migration (longer window)
    new MaintenanceWindow("database-migration", {
      name: "Database Schema Migration",
      tags: ["database", "migration"],
      startsAt: new Date("2025-02-22T01:00:00.000Z"),
      endsAt: new Date("2025-02-22T07:00:00.000Z"), // 6-hour window
    })
    ```
  </Tab>
</Tabs>

## Best Practices

<Warning>
  **Tag Matching**: Maintenance windows affect ALL checks that have ANY of the specified tags. Be specific with your tags to avoid affecting unintended checks.
</Warning>

<Info>
  **Time Zones**: Always use UTC timestamps for consistency across different time zones. Convert your local maintenance times to UTC.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.