Skip to main content

​
Overview

Maintenance windows allow you to suppress alerts during planned maintenance periods. This endpoint returns all maintenance windows configured in your account, including their schedules and affected resources.
During maintenance windows, checks continue to run but alerts are suppressed. This prevents unnecessary notifications during planned downtime.

​
Response Example

{
  "data": [
    {
      "id": "mw_123456789",
      "name": "Weekly Server Maintenance",
      "startsAt": "2024-01-28T02:00:00.000Z",
      "endsAt": "2024-01-28T04:00:00.000Z",
      "repeatInterval": "WEEKLY",
      "repeatEndsAt": "2024-12-31T23:59:59.000Z",
      "tags": ["server", "weekly"],
      "checkIds": [
        "check_abc123",
        "check_def456"
      ],
      "checkGroupIds": [
        "group_789123"
      ],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:00.000Z"
    },
    {
      "id": "mw_987654321",
      "name": "Database Migration",
      "startsAt": "2024-02-01T20:00:00.000Z",
      "endsAt": "2024-02-01T23:00:00.000Z",
      "repeatInterval": "NONE",
      "tags": ["database", "migration"],
      "checkIds": [
        "check_ghi789"
      ],
      "createdAt": "2024-01-25T08:15:00.000Z",
      "updatedAt": "2024-01-25T08:15:00.000Z"
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 2,
    "limit": 10
  }
}

​
Maintenance Window Types

Single maintenance window for specific events:
  • Use Cases: Software deployments, database migrations, hardware upgrades
  • Repeat Interval: NONE
  • Duration: Specific start and end times
Example:
{
  "name": "Production Deployment",
  "startsAt": "2024-02-15T18:00:00.000Z",
  "endsAt": "2024-02-15T20:00:00.000Z",
  "repeatInterval": "NONE"
}
Regular maintenance windows that repeat:
  • Daily: Every day at the same time
  • Weekly: Same day and time each week
  • Monthly: Same date each month
Example:
{
  "name": "Nightly Backup Window",
  "startsAt": "2024-01-20T02:00:00.000Z",
  "endsAt": "2024-01-20T04:00:00.000Z",
  "repeatInterval": "DAILY",
  "repeatEndsAt": "2024-12-31T23:59:59.000Z"
}
Control which resources are affected:
  • Specific Checks: Target individual checks by ID
  • Check Groups: Target all checks in specific groups
  • Combined: Mix of individual checks and groups
Benefits:
  • Granular control over alert suppression
  • Maintain monitoring for unaffected services
  • Easy management of related resources

​
Code Examples

curl -X GET "https://api.checklyhq.com/v1/maintenance-windows" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

​
Use Cases

Scheduled Deployments

Suppress alerts during planned software deployments and updates

Infrastructure Maintenance

Silence monitoring during server maintenance and hardware upgrades

Backup Windows

Avoid alerts during nightly backups and database maintenance

Third-party Maintenance

Handle known downtime from external service providers

​
Filtering Options

Filter maintenance windows by various criteria:
  • limit (integer): Number of results per page (max 100)
  • page (integer): Page number (1-based)
  • active (boolean): Show only currently active windows
  • upcoming (boolean): Show only future windows
  • tag (string): Filter by tag
# Get active maintenance windows
curl -X GET "https://api.checklyhq.com/v1/maintenance-windows?active=true" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

# Get upcoming maintenance windows
curl -X GET "https://api.checklyhq.com/v1/maintenance-windows?upcoming=true" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

# Filter by tag
curl -X GET "https://api.checklyhq.com/v1/maintenance-windows?tag=database" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

​
Status Indicators

Determine if a maintenance window is currently active:
function isMaintenanceActive(window) {
  const now = new Date();
  const starts = new Date(window.startsAt);
  const ends = new Date(window.endsAt);
  
  return now >= starts && now <= ends;
}
Check if a maintenance window is scheduled in the future:
function isMaintenanceUpcoming(window) {
  const now = new Date();
  const starts = new Date(window.startsAt);
  
  return starts > now;
}
Maintenance windows are essential for managing alert fatigue during planned maintenance. They ensure your team only receives notifications for unexpected issues, not planned downtime.