GET
/
v1
/
maintenance-windows
List all maintenance windows
curl --request GET \
  --url https://api.checklyhq.com/v1/maintenance-windows \
  --header 'Authorization: <api-key>'
[
  {
    "id": 1,
    "name": "Maintenance Window",
    "tags": [
      "production"
    ],
    "startsAt": "2022-08-24",
    "endsAt": "2022-08-25",
    "repeatInterval": "null",
    "repeatUnit": "DAY",
    "repeatEndsAt": "null",
    "created_at": "2023-12-25",
    "updated_at": "2023-12-25"
  }
]

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

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

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