MaintenanceWindow Construct

Learn more about Maintenance Windows in the Maintenance Windows documentation.

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

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

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

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

string

required

A name for the maintenance window that will be displayed in the Checkly dashboard and used for identification.Usage:

new MaintenanceWindow("my-maintenance", {
  name: "Weekly Database Backup",
  /* More options... */
})

Use cases: Window identification, dashboard display, maintenance tracking.

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:

new MaintenanceWindow("my-maintenance", {
  name: "API Maintenance",
  tags: ["api", "backend"],
  /* More options... */
})

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

Use cases: Service targeting, environment isolation, maintenance scope control.

Date

required

Start date and time for the maintenance window in UTC (ISO 8601 timestamp).Usage:

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.

Date

required

End date and time for the maintenance window in UTC (ISO 8601 timestamp).Usage:

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.

number

Repeat interval from the first occurrence. Used with repeatUnit to create recurring maintenance windows.Usage:

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.

string

Repeat strategy that defines the time unit for recurring maintenance windows (DAY | WEEK | MONTH).Usage:

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

Examples:

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"],
})

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"],
})

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"],
})

Use cases: Time-based recurrence patterns, maintenance scheduling consistency, automated repetition.

Date

When to stop repeating the maintenance window (ISO 8601 timestamp in UTC). If not specified, the maintenance window will repeat indefinitely.Usage:

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.

string

The named IANA time zone 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. 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:

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

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.

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

boolean

default:"false"

Pause every check in the account during the maintenance window, regardless of tags.Usage:

new MaintenanceWindow("platform-migration", {
  name: "Platform Migration",
  pauseAllChecks: true,
  /* More options... */
})

Use cases: Account-wide migrations, full platform downtime.

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:

new MaintenanceWindow("degraded-api", {
  name: "Expected API Degradation",
  silenceAlertsTags: ["api"],
  /* More options... */
})

Use cases: Keep monitoring during expected degradation without noisy alerts.

boolean

default:"false"

Silence alerts for every check in the account during the maintenance window, regardless of silenceAlertsTags. Checks keep running.Usage:

new MaintenanceWindow("quiet-period", {
  name: "Quiet Period",
  silenceAllAlerts: true,
  /* More options... */
})

Use cases: Account-wide alert silencing while monitoring continues.

Examples

Database Maintenance
Weekly System Updates
Emergency Maintenance
Service-Specific Maintenance

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

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

// 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)
})

// 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
})

Best Practices

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

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

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

MaintenanceWindow Construct

Configuration

`MaintenanceWindow` Options

Examples

Best Practices

​Configuration

​MaintenanceWindow Options

​Examples

​Best Practices

Configuration

`MaintenanceWindow` Options

Examples

Best Practices