Skip to main content
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"),
})

​
Configuration

ParameterTypeRequiredDefaultDescription
namestring✅-Name of the maintenance window
startsAtDate✅-Start date and time (ISO 8601 timestamp)
endsAtDate✅-End date and time (ISO 8601 timestamp)
tagsstring[]✅-Tags that filter which checks are affected
repeatIntervalnumber❌-Repeat interval from the first occurrence
repeatUnitstring❌-Repeat strategy: 'WEEK' | 'MONTH' | 'YEAR'
repeatEndsAtDate❌-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:
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"],
})
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

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

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