Maintenance windows
Plan work on your services once. One window pauses the right alerts, leaves the time out of uptime, shows on your status pages and emails subscribers, while checks keep running.
A maintenance window is planned work with a start and an end. One window does all of this for the monitors and components it targets:
- Pauses alerts for what the work can interrupt. Certificate and domain expiry stay live.
- Leaves the time out of uptime, so planned work doesn't count as downtime. See the definition.
- Shows on every published status page that displays a target. See what visitors see.
- Emails the subscribers of those pages. See which emails go when.
Checks keep running, and they count as usage. Every check inside a window is stored and billed like any other, so you can see what happened during the work. A monitor's status also stays what the checks measured: a site that is down during a window reads as down on its monitor page, with a line saying the window holds it.
Open Maintenance in the Monitor sidebar, then Schedule maintenance. A status
page's Maintenance tab lists the windows on that page, and scheduling from there
selects that page for you. From a terminal, use
nrc monitor maintenance.
There are no recurring windows: each window is one occurrence, with absolute times.
Lifecycle
A window's state follows from its times, so it can't drift from them.
| State | The API says | When |
|---|---|---|
| Scheduled | scheduled | Before the start |
| In progress | in_progress | From the start until the end |
| Completed | completed | After the end |
| Canceled | cancelled | Called off before the start |
What you can do in each state:
| Change | Scheduled | In progress | Completed | Canceled |
|---|---|---|---|---|
| Title and description | Yes | Yes | Yes | No |
| Email switches | Yes | Yes | No | No |
| Targets | Yes | No, frozen | No | No |
| Start | Yes, to a future time | No | No | No |
| End | Yes, to a future time | Yes, to a future time | No | No |
| Finish (end it now) | No | Yes | No | No |
| Cancel | Yes | No | No | No |
| Delete | No | No | No | Yes |
A change the state refuses answers 409 with the reason MAINTENANCE_WINDOW_STATE,
and data.state says where the window stands. Sending a field with the value it
already has isn't a change, so it is never refused.
- Nothing that has already happened can change. A window that started can't be canceled, only finished, so the time it ran stays explained.
- A completed window can't be deleted. It explains a gap in uptime, and goes by itself 2 years after it ended.
- A canceled window can be deleted once its cancellation has been handed to subscribers, within about a minute. Before that, deleting answers 409.
- A start up to 5 minutes in the past starts now, which allows for a clock a little behind. Further back is refused.
Targets
A window targets monitors and manual status page components. It needs at least one.
- HTTP and SSL monitors can be targets. Domain monitors can't: a domain's
registration isn't affected by maintenance, so naming one answers 422
UNPROCESSABLE. - A whole page is a shortcut. It expands to the monitors and manual components the page shows when you save, leaving out domain monitors. A component you add to the page later doesn't join the window.
- Which pages show a window isn't a choice. A window shows on every page that displays a target, with no opt-out per page. Otherwise a page could stay green while its alerts are silenced.
- A component that only watches a certificate or a domain isn't affected. A monitor
component counts as affected if it counts
availability, or the aspect the monitor's kind primarily judges. So a component counting only an HTTP monitor'scertificatestays live, and that page doesn't show the window because of it. - If every target is deleted before the start, the window cancels itself. The audit
log records it as
auto_cancelled.
A window that no published page shows is internal: it still pauses alerts and leaves uptime alone, and only preview links show it.
What stays live
Calendar conditions keep alerting and opening incidents as usual, because a certificate or a domain runs out whatever work is going on.
| Stays live during a window | Held during a window |
|---|---|
| A certificate expiring or expired, on an SSL monitor or an HTTP expiry watch | HTTP availability: down, slow, a configuration error, a request refused over its certificate |
| Everything about a domain, on an HTTP expiry watch | An SSL monitor's unreachable host, and invalid, wrong-hostname or not-yet-valid certificates |
Incidents
| Situation | What happens |
|---|---|
| A held problem, no incident open | No incident and no alert. The confirmation count starts over. |
| A held problem, an incident already open | The incident doesn't change: no new severity and no alert. A real escalation after the window still alerts. |
| The first time a window holds an open incident | It shows Alerts paused, with one timeline entry naming the window. |
| The reminder of a held incident comes due | It isn't sent. If the outage outlasts the window, the next one goes within its normal interval. |
| Checks pass during the window, on a held incident | It stays open. The first passing check after the end resolves it, with recovered. |
| Checks pass during the window, on a certificate or domain incident | It recovers as usual, with its alert. |
| A problem starts just after the end | It needs the normal confirmation, unless its kind opens at once. |
A down alert was queued before the window started | It is still delivered: it was decided before the window, and on-call needs it. |
An extra check at the end. A monitor with a long interval would otherwise take a long time to notice it recovered. So once a window ends, an enabled monitor with a held incident gets its next check right away, unless another window still holds it. That is one extra check, counted as usage.
Held incidents leave the open counts and the mean time to resolve. See Incidents.
Uptime
A check counts as inside a window if the window had begun when the check finished and hadn't ended when it started, so a check spanning either edge counts as inside. Inside and outside then add up separately:
- Uptime is
(ok + warning) / (ok + warning + critical), over checks outside maintenance. Inconclusive checks count neither way. - Downtime for a day is the critical share of its conclusive checks outside maintenance, multiplied by the minutes those checks cover, and never more than the day so far less the minutes under maintenance.
- Maintenance minutes are shown separately. They come from the window's times, so they are exact, whatever the check interval.
- A day with nothing conclusive outside a window has the grade
maintenance. A day that is only partly under maintenance keeps its normal grade and adds its minutes.
Worked example
A monitor checks every 60 seconds for a full UTC day, with a window from 02:00 to 04:00. The site is down throughout the window. Outside it, 10 checks fail and 5 are slow.
| Figure | Value |
|---|---|
| Checks billed | 1,440 |
| Checks inside the window | 120 (maintenance) |
| Checks outside | 1,320 (checks): 1,305 ok, 5 warning, 10 critical |
| Uptime | 1,310 / 1,320 = 99.24% |
| Downtime | 10 minutes, so the day's grade is minor |
| Maintenance | 120 minutes, shown separately |
Had the window counted, the same day would read 1,310 / 1,440 = 90.97%.
So in the API, a day's checks isn't what you pay for: the billed count is
checks + maintenance. See Pricing.
What visitors see
The fixed words below are translated into the page's eight languages. Your title and description stay as written.
- Before the start, the verdict doesn't change. Scheduled maintenance lists the soonest 20 windows, below the services.
- During the window, each affected component reads Under maintenance, then "Until 16:00". Maintenance in progress lists the window at the top, with its times, the components it affects and its description.
- The verdict is Under maintenance when every component with data is in maintenance, and Partial maintenance when some are. A real problem keeps its own verdict and comes first, with maintenance listed below it. See The page's verdict.
- The bars mark a day that was all maintenance, and every day's details add its minutes.
/maintenance/<id>is the window's own page, and/historylists past windows with resolved posts.- Feeds and data carry windows too. See Public data.
Maintenance is blue, with a clock mark and always a word.
A posted incident you write outranks a window on the components it names, and a window outranks an automatic post.
Timing at the boundaries
Alerts and uptime are exact. A check is stamped when it is stored, so a window starting or finishing applies from the next result.
The public page can lag by about 3 minutes. When a window starts or ends on its own, nothing has been saved, so the page is rebuilt by its next pass. Finish, Cancel and any other edit count as saved changes, and are public within a minute.
That is why every time on a page and in an email is absolute and names its time zone, such as "6 Nov 2026, 14:00–16:00", and never says "in 5 minutes". Pages use the status page's time zone. In the dashboard, you enter times in your browser's time zone.
Which emails go when
Three switches on the window decide what subscribers get, all on by default in the dashboard and the CLI. The API requires all three, so nothing emails subscribers because a field was left out.
| Switch | Dashboard label | Sends |
|---|---|---|
notifyScheduled | When it is scheduled | Scheduled maintenance, and Maintenance rescheduled after a move |
notifyStarted | When it starts | Maintenance started |
notifyFinished | When it is finished | Maintenance finished, or Maintenance finished early |
| Case | |
|---|---|
| Created 15 minutes or more ahead | Scheduled |
| Created under 15 minutes ahead, or already started | One email at the start, none before it |
| Text or switch edited before the start | None |
| Start or end moved 5 minutes or more, subscribers were told | Rescheduled |
| Start or end moved, nobody told yet | Scheduled, if the new start is still 15 minutes or more away |
| A new page starts showing it before the start | Scheduled, for that page |
| A page stops showing it before the start, after an email | Canceled, for that page, with no link |
| Canceled before the start | Canceled, only where an earlier email went, whatever the switches say |
| It starts | Started, up to 30 minutes after the start, and never after the end |
| End changed while in progress | None. The page updates, and the finished email has the true end |
| It ends, or someone finishes it | Finished, up to 2 hours after the end |
| A page stops showing it after the start | No cancellation. Readers told it started still hear it finished |
An email that can't go out in time is dropped rather than sent late, and an email waiting to go is dropped when a newer one about the same window reaches the same page. Only published pages send anything, and an organization blocked over unpaid invoices sends nothing.
Each page sends its own emails, naming that page's affected components, so a subscriber who chose other components hears nothing. Each email counts as usage, like every subscriber email.
Reminders for long windows
Nobody should forget that alerts are off for days. The form says "Alerts stay paused for 7 days" for anything over 24 hours, and a window over 24 hours emails the organization's members a day after its start, and then daily: "Alerts for N monitors are still paused until X". These emails are in English, count against the daily email cap and aren't billed.
Permissions
Every route needs the window's own IAM action, and a token also needs the scope:
| Action | Allows |
|---|---|
monitor:ListMaintenanceWindows | Listing windows, and what a window could target |
monitor:GetMaintenanceWindow | Reading a window |
monitor:CreateMaintenanceWindow | Creating a window |
monitor:UpdateMaintenanceWindow | Changing, finishing and canceling a window |
monitor:DeleteMaintenanceWindow | Deleting a canceled window |
monitor:PublishMaintenanceWindow | Showing a window on a status page and emailing its subscribers |
Two more checks depend on the targets:
- Silencing is as strong as pausing. Creating a window, or changing its targets or times,
also needs
monitor:UpdateMonitoron every monitor it silences. Otherwise it answers 403FORBIDDEN, withdata.monitorIds. - Going public takes permission to publish. Creating or changing a window that shows on a
published page, before or after the change, needs
monitor:PublishMaintenanceWindowon each such page. Otherwise it answers 403FORBIDDENwith the reasonMAINTENANCE_PUBLISH_DENIED, naming the page, withdata.statusPageIds. In the dashboard the button is disabled, and a hint names the page.
Finish and cancel need only monitor:UpdateMaintenanceWindow, so whoever can edit a window
can always end its silence.
Scopes
Any Norcube Monitor scope reads windows. Changing one takes monitor.maintenance, which no other
scope includes. It can't publish, so a deploy token can't announce something or quietly hide
an outage unless you granted that on purpose. For that, add monitor.statuspages.
| Caller | No published page | Published page |
|---|---|---|
| Dashboard or full CLI sign-in | IAM on each monitor | IAM on each monitor and on the page |
CI token, monitor.maintenance | Allowed | 403 |
CI token, with monitor.statuspages too | Allowed | Allowed |
Scoped CLI sign-in, monitor.maintenance | IAM on each monitor | 403, whatever the user's role |
Scoped CLI sign-in, with monitor.statuspages too | IAM on each monitor | IAM on each monitor and on the page |
| Any other scope | 403 INSUFFICIENT_SCOPE | 403 INSUFFICIENT_SCOPE |
The audit log records created, updated, cancelled, finished and deleted, and the
system's auto_cancelled, on the target maintenance_window.
Limits
| Limit | Value | Past it |
|---|---|---|
| Windows scheduled or in progress, per organization | 100 | 403 LIMIT_REACHED, reason MAINTENANCE_WINDOW_LIMIT |
| Monitors and components in one window | 500 | 403 LIMIT_REACHED, reason MAINTENANCE_WINDOW_LIMIT |
| Length of a window | 30 days | 400 VALIDATION_FAILED |
| How far ahead it can start | 365 days | 400 VALIDATION_FAILED |
| Title | 200 characters | 400 VALIDATION_FAILED |
| Description (public) | 2,000 characters | 400 VALIDATION_FAILED |
| Kept after it ended | 2 years |
These are safety caps, not plan limits. A status page carries every window in progress, the
soonest 20 scheduled, and the 50 newest past ones within its historyDays. A canceled window
stays in that history only if subscribers heard about it, so the link in their email keeps working.
From the CLI
The nrc monitor maintenance commands need CLI 0.25.0. A window is named by
its id.
nrc monitor maintenance list --state scheduled
nrc monitor maintenance list --monitor "Shop API"
nrc monitor maintenance get <window>
nrc monitor maintenance create \
--title "Database upgrade" \
--description "Short interruptions are expected." \
--monitor "Shop API" \
--status-page acme \
--start 2026-11-20T14:00:00Z \
--duration 2h
nrc monitor maintenance update <window> --end +3h
nrc monitor maintenance cancel <window> # scheduled only; asks first
nrc monitor maintenance finish <window> # in progress only; doesn't ask--start and --end take an RFC 3339 timestamp, now, or a time from now such as +2h.
A bare 2h is refused. --start defaults to now, and either --end or --duration is required.
--monitor, --component and --status-page can repeat, and on update any of them
replaces the targets as a whole. The three --notify-* flags default to on, and --no-notify
turns them all off.
Without a terminal, cancel needs --yes. There is no delete command. Use
nrc api monitor DELETE /maintenance-windows/<id> for a canceled window.
Around a deploy
-o id prints only the result's id:
id=$(nrc monitor maintenance create --monitor api --title "Deploy" --duration 15m -o id)
./deploy.sh
nrc monitor maintenance finish "$id"Give the CI token monitor.maintenance, and monitor.statuspages too if a published page shows
the monitor. If the pipeline dies before finish, the window ends by itself when its duration
is up, so keep the duration close to what a deploy takes.
During a window, nrc monitor status --fail-on doesn't fail on incidents the window holds.
nrc monitor monitors run --wait still fails on a critical result, since it exists to check
whether the deploy worked. See Gate a deploy.
Through the API
Each route is under /maintenance-windows; see the API page. A new
window takes all three email switches and targets:
{
"title": "Database upgrade",
"description": "Short interruptions are expected.",
"startsAt": "2026-11-20T14:00:00Z",
"endsAt": "2026-11-20T16:00:00Z",
"notifyScheduled": true,
"notifyStarted": true,
"notifyFinished": true,
"targets": {
"monitorIds": ["7d1c2f7e-6a1f-4f5e-9b8a-1f7c2b3d4e5f"],
"componentIds": [],
"statusPageIds": []
}
}statusPageIds expands when saved and isn't stored, so a response has only monitorIds and
componentIds. A response adds state, finishedEarly and statusPages, the pages it shows on,
published or not, with the components it affects there.
Incidents
How an incident opens, escalates, reminds and resolves, what its severity and aspect mean, how to acknowledge one, and how to read the incidents page and an incident's timeline.
Create a status page
A public page that shows chosen monitors under names you pick. Choose its address and settings, set what it shows, check it, then publish it.