MaintenanceWindow Construct

Learn how to configure maintenance windows with the Checkly CLI.

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.

One-Time Maintenance

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 affected
repeatInterval	number	❌	-	Repeat interval from the first occurrence
repeatUnit	string	❌	-	Repeat strategy: 'WEEK' | 'MONTH' | 'YEAR'
repeatEndsAt	Date	❌	-	When to stop repeating (ISO 8601 timestamp)

MaintenanceWindow Options

name · 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.

tags · string[] · required

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.

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.

startsAt · 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.

endsAt · 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.

repeatInterval · 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.

repeatUnit · 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:

Daily Maintenance

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.

repeatEndsAt · 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.

Examples

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

Weekly System Updates

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

Emergency Maintenance

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

Service-Specific Maintenance

// 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.