List Maintenance Windows

Retrieve all maintenance windows in your account

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

One-time Maintenance

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

Recurring Maintenance

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

Resource Targeting

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

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

Query Parameters

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

Example Requests

# 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

Active Status

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

Upcoming Status

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.

Authorizations

Authorization · string · header · required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here. Your API key is like a password: keep it secure! Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID. For example, set Authorization header while using cURL: curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

x-checkly-account · string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Query Parameters

limit · integer · default: 10

Limit the number of results

Required range: 1 <= x <= 100

page · number · default: 1

Page number

startsAt · string

endsAt · string

Response

200

application/json

Successful

id · number · required

The id of the maintenance window.

Example:

1

name · string · required

The maintenance window name.

Example:

"Maintenance Window"

startsAt · string<date> · required

The start date of the maintenance window.

Example:

"2022-08-24"

endsAt · string<date> · required

The end date of the maintenance window.

Example:

"2022-08-25"

repeatUnit · string · required

The repeat strategy for the maintenance window.

Example:

"DAY"

created_at · string<date> · required

The creation date of the maintenance window.

updated_at · string<date> · required

The last date that the maintenance window was updated.

tags · string[]

The names of the checks and groups maintenance window should apply to.

Example:

["production"]

repeatInterval · number

The repeat interval of the maintenance window from the first occurance.

Required range: x >= 1

Example:

null

repeatEndsAt · string<date>

The end date where the maintenance window should stop repeating.

Example:

null