> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Scheduled Maintenance
> Announce planned work ahead of time with a maintenance window — a titled, markdown notice with a start/end time and affected components that surfaces on your public status page.
A **scheduled maintenance window** is a planned-work notice on your [public status page](/concepts/status-pages): a title, a markdown body ("we're upgrading the database engine Saturday 02:00–03:00 UTC"), a start and end time, and the set of components the work affects. Visitors see upcoming, in-progress, and recently-completed windows in a dedicated section, and the affected components switch to **maintenance** for the duration.
## Windows vs. per-component maintenance
scaling.cloud has two ways to surface planned work, and they're for different jobs:
| | Per-component maintenance | Scheduled maintenance window |
| --------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| What it is | A [manual override](/guides/publish-status-page) flipping **one** component to `maintenance` | A standalone **notice** with a title, body, time window, and **multiple** affected components |
| Carries a message | No | Yes — a markdown body shown publicly |
| Planned ahead of time | Set it when you want it | Yes — has an explicit start/end |
| Appears as | A component status | Its own card in the **Scheduled Maintenance** section |
Use a per-component override for a quick "this one thing is down for maintenance right now." Use a window when you want to **announce** planned work — its scope, timing, and impact — to customers.
## The lifecycle
A window moves through an explicit lifecycle:
```
scheduled ──▶ in_progress ──▶ completed
│ │
└──────┬───────┘
▼
cancelled
```
| State | Meaning |
| ------------- | -------------------------------------------------------------- |
| `scheduled` | Created and announced; the work hasn't started. |
| `in_progress` | The work has started. |
| `completed` | The work is done. Terminal. |
| `cancelled` | Called off before completing. Terminal — never shown publicly. |
You drive these transitions yourself from the dashboard (**Start**, **Complete**, **Cancel**). `cancel` is allowed from either `scheduled` or `in_progress`; once a window is `completed` or `cancelled` it's terminal and can't be edited or transitioned.
**A window goes live by the clock, not by a button.** On the public page, a window is treated as active whenever the current time is within `[start, end)` and it hasn't been completed or cancelled — even if no one has clicked **Start** yet. You don't need to be online at 02:00 for the page to show the maintenance as in progress. The explicit **Start** / **Complete** transitions exist to drive your own workflow (and to time customer notifications precisely), not to gate the public display.
## How windows appear publicly
On the public page, each non-cancelled window is shown with one of three states, derived from the current time:
| Public label | When |
| --------------- | -------------------------------------------------------------------------------------- |
| **Upcoming** | The current time is before the window's start. |
| **In Progress** | The current time is within the window. |
| **Completed** | The window's end time has passed — shown for **48 hours**, then it drops off the page. |
Cancelled windows never appear on the public page.
### The maintenance body is sanitised markdown
The body you write supports **markdown** — headings, bold/italic, lists, and links — so you can link to a tracking issue or list the expected impact. It renders to HTML on the server, run through a strict allow-list sanitiser: scripts, event handlers, inline styles, and unsafe link schemes are stripped before anything reaches a visitor's browser. Write freely; the sanitiser is the safety boundary.
### Affected components show as maintenance
While a window is active, every component in its affected set switches to the `maintenance` status on the page — unless something worse is already true for that component. The read-time precedence is:
1. **Manual override** set by an admin.
2. **Open incident** tagging the component — the worst severity wins.
3. **Active maintenance window** → `maintenance`.
4. **Default** — `operational`.
So a real incident (`degraded` or worse) on a component always outranks a maintenance window touching the same component — genuine problems are never masked by planned work.
### Maintenance escalates the overall banner
When the worst thing happening across your components is maintenance — and nothing worse — the **overall banner reads "Under maintenance."** This is a distinct, expected (blue) signal, not a "we have issues" warning. The full ranking is:
```
major_outage > partial_outage > degraded > maintenance > operational
```
This applies to **both** sources of maintenance — an active scheduled window **and** a manual per-component `maintenance` override both raise the banner to "Under maintenance." (This is a deliberate change: maintenance previously did not escalate the banner at all.)
## In the JSON feed
The [public JSON feed](/concepts/status-pages#json-api) includes the windows alongside components and incidents:
```
GET https://scaling.cloud/api/public/status/
```
```json theme={null}
{
"overall": { "kind": "maintenance" },
"maintenances": [
{
"id": "…",
"title": "Database engine upgrade",
"body": "We're upgrading Postgres. Expect brief read-only windows.",
"bodyHtml": "We're upgrading Postgres…
",
"state": "active",
"scheduledStartAt": "2026-06-06T02:00:00.000Z",
"scheduledEndAt": "2026-06-06T03:00:00.000Z",
"affectedComponents": [{ "id": "…", "name": "API" }]
}
]
}
```
`body` is the raw markdown; `bodyHtml` is the sanitised HTML already rendered for you. `overall.kind` can now be `maintenance`.
## Next steps
* [Schedule a maintenance window](/guides/schedule-maintenance-window) — the step-by-step walkthrough.
* [Public status pages](/concepts/status-pages) — how component status and the overall banner are derived.