Maintenance windows

A maintenance window is a time range during which monitors with matching tags don’t page. Checks still run and failures are still recorded; they just don’t reach humans while the window is active.

Use maintenance windows for:

Scheduled deploys: the four-second blip during your zero-downtime rollout shouldn’t page anyone.
Database migrations: the ten-second connection-pool restart isn’t an outage.
Vendor maintenance: your CDN’s scheduled maintenance shouldn’t page you.
Long-running batch jobs: the queue spike during nightly ETL is expected.

Two types

One-time

A single starts_at / ends_at pair. Fire-and-forget for one specific deploy or operation.

{
  "name": "Friday API deploy",
  "tags": ["service:api"],
  "schedule_type": "one_time",
  "starts_at": "2026-05-10T14:00:00Z",
  "ends_at": "2026-05-10T14:30:00Z"
}

Recurring

A recurrence rule. Two flavors:

Daily, the same window every day:

{
  "name": "Nightly batch ETL",
  "tags": ["service:etl"],
  "schedule_type": "recurring",
  "timezone": "America/Los_Angeles",
  "recurrence": {
    "type": "daily",
    "start_time": "02:00",
    "end_time": "03:00"
  }
}

Weekly, the same window on chosen days each week:

{
  "name": "Sunday maintenance window",
  "tags": ["env:prod"],
  "schedule_type": "recurring",
  "timezone": "UTC",
  "recurrence": {
    "type": "weekly",
    "days": ["sunday"],
    "start_time": "02:00",
    "end_time": "04:00"
  }
}

start_time and end_time are 24-hour HH:MM in the window’s timezone (defaults to UTC). Days accept full English names (monday .. sunday) or three-letter abbreviations (mon .. sun), case-insensitively; anything else is rejected at creation.

How tags match

Each maintenance window has a list of tags. Monitors also have tags. A monitor is silenced when its tags overlap with an active window’s tags, meaning at least one tag appears in both lists. That’s the whole rule:

There is no wildcard tag. To silence everything, give every monitor a shared tag (for example env:prod) and put that tag on the window.
A window’s tags must be non-empty (the API rejects an empty list).
A monitor with no tags never matches any window and is never silenced.

Patterns we recommend:

service:<name> to silence everything in a service.
env:<name> to silence everything in an environment.
type:cron to silence all cron checks.

What “silenced” means precisely

Suppression applies to monitor notifications that carry monitor context (HTTP and cron monitors). While a matching window is active:

Checks still run on schedule. Results are recorded.
Failure notifications are held, not dropped. They are stored and re-evaluated when the window’s current occurrence ends, so a monitor that is still down after the window pages then.
Recovery notifications are suppressed and clear the held failure for that monitor, so a blip fully inside the window pages no one.
Auto-created incidents still open for services configured to open them; the maintenance window suppresses the monitor’s notification fanout, not incident creation.
Status pages keep showing live status unless you also publish a status page maintenance entry.

is_currently_active on the response tells you whether the window is in effect right now (computed against the server clock).