title: "Maintenance windows" description: "Suppress alerts during planned work without losing your metrics." last_updated: "2026-05-24"

Maintenance windows

A maintenance window is a time range during which BoxWatch will keep collecting metrics but suppress all alerts for the targeted server or group. Use them for OS upgrades, planned deploys, hardware swaps — anything where you expect noise.

Metrics are not paused. Your graphs stay intact, so you can review what happened during the window after the fact.

What gets suppressed

Inside an active window, BoxWatch skips dispatch for any of:

• Server offline (no heartbeat received).
• Threshold alerts (CPU, memory, disk).
• Disk full projection.
• Watched-process alerts (down, restarted, CPU high, memory high).
• Uptime check failures, when the failure is observed by an agent running on the maintained server.
• Cron checks that are linked to the server. A check with no linked server is unaffected.

The alert state is still updated internally — only the dispatch is skipped. That way you don't get a backlog burst the moment the window ends.

What doesn't get suppressed

• Cron checks not linked to a server. They're job-level, not host-level.
• Uptime checks running from other servers. If a check is assigned to web-01 and web-02, putting web-01 in maintenance still lets web-02's probe trigger a down alert.
• Auth events, account-level notifications, billing emails.

Creating a window

From the dashboard, open the server detail page and click Schedule maintenance. Pick a title, start time, end time, and optional notes. Times are in your account's timezone.

Or use the API:

curl -X POST https://api.boxwatch.app/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": 42,
    "title": "Kernel upgrade",
    "notes": "Reboot expected",
    "start_time": "2026-05-25T02:00:00Z",
    "end_time":   "2026-05-25T03:00:00Z"
  }'

Provide exactly one of server_id or group_id. Both is rejected; neither is rejected.

{
  "window": {
    "id": 9,
    "server_id": 42,
    "group_id": null,
    "title": "Kernel upgrade",
    "notes": "Reboot expected",
    "start_time": "2026-05-25T02:00:00Z",
    "end_time":   "2026-05-25T03:00:00Z",
    "created_at": "2026-05-24T18:42:00Z"
  }
}

Group-wide windows

Pass group_id instead of server_id to silence an entire group at once. All servers in that group inherit the window for its duration. This is useful for fleet-wide events — a base-image rebuild, a coordinated cron change.

See Server groups for how to set them up.

Listing and editing

Returns active, upcoming, and recently-expired windows (anything ending within the last 24 hours).

Update title, notes, start, or end. You can extend an active window if maintenance runs long.

Cancel a window. If it was active, alerts resume immediately.

After the window ends

When end_time passes, alerting resumes on the next eligible event. There is no retroactive replay — alerts that would have fired during the window stay suppressed.

Practical implication: if a watched process was already down before the window opened and is still down when the window closes, you'll get a fresh alert on the next heartbeat because the internal state transition (down→down) doesn't change. If it broke during the window and is still broken at the end, you'll get an alert on the next heartbeat that detects the still-broken state.

Notes

• There's no recurring-window feature in v1. For weekly OS-patch windows, schedule them ahead with a small script that POSTs once a week.
• A window is owned by your user account. Other team members can see and edit it through their own dashboard sessions.
• Maintenance affects alert dispatch only. Status pages (if you have any) continue to show real metric state.