Skip to content
Docs menu

Status page uptime checks, maintenance and subscribers

Watch your own services from the cloud with http, TCP and heartbeat checks, feed the status page's uptime bars and response-time charts, page on-call when a check keeps failing, schedule maintenance, and let readers follow by RSS, Atom or a signed webhook.

View .md

The public status page shows your models' uptime from your own traffic. Uptime checks add the rest of your stack: your website, your API, a database port, a nightly job. Each check feeds the uptime bars of the service it belongs to, draws a response-time chart, and raises an alert when it keeps failing. It is the same page at /status/{slug}; there is no second one.

Everything is under Settings → Status page. Reading is org:read, changing is org:manage. Agents do the same through the workspace MCP server (status_* tools, scopes status:read and status:write) and its REST twin under /api/v1/status.

Services and groups

A service on the page is a component: an id, the name people see and an optional group. For a model the id is the model id (as before). For anything else, use Add another service in the page form and pick an id such as website. Groups head sections of the public page ("API", "Dashboard"); services without a group come first.

Uptime checks

Kind What it does Fields
Website or API (http) Requests the address from the cloud url, method (GET, HEAD, POST), expected_status (200-299 or 200,204), keyword (must be in the first 256 KB of the body; keyword_absent flips it), timeout_ms (1 to 30 s)
TCP port (tcp) Opens a connection and closes it host, port, timeout_ms
Heartbeat (heartbeat) Waits for your own job to call a secret URL interval_s, grace_s

Every check also has interval_s, fail_after (failed runs in a row before an alert; default 3), the service it shows under (component) and an on/off switch. At most 50 checks per organisation.

How often. A cron runs once a minute (/api/cron/status-checks), so the shortest interval is 60 seconds. A check with a 60 second interval runs on every tick; one with 5 minutes runs on every fifth. Each tick runs at most 120 due checks, ten at a time, within 40 seconds; a check left over is picked up on the next tick. Vercel cron has no sub-minute granularity, and a busy tick can start a check a few seconds late. Checks run from the cloud's region, not from several places.

Where it calls. Only the addresses you enter. In production the address must be https on the public internet: loopback, private, link-local and metadata addresses are refused (so is a name that resolves to one, checked again when the socket connects), and redirects are not followed. A server on your own network needs a daemon next to it; a check can't reach it. Off production (a local make cloud-dev) a loopback target is allowed.

Heartbeats. Creating a heartbeat shows a secret URL once, https://…/api/status/heartbeat/vhb_…. Have your cron job request it (GET or POST) each time it finishes. If no ping arrives within the interval plus the grace, the check fails. A ping on a failing heartbeat passes it at once. Only a hash of the token is kept; New secret URL in the row menu makes another and stops the old one. Copy the URL when you see it: it is shown in a notice that goes away.

Results. Each run stores its outcome, status code, latency and error. Raw results are kept 7 days and rolled up by the hour for 90. A check's page in the API (GET /status-page/checks/{id}/results) lists the runs and the last 24 hours' uptime and latency.

What the public page shows

A service with checks draws its 30-day bars and uptime from them (a failed run counts against it) and shows a response-time chart for the last 24 hours when it has an http or TCP check. A service without checks keeps drawing from your own traffic. The page never shows a check's name, address or token, only the service's name and numbers.

Alerts

Pick an Incidents alert source on the page form (make one under Incidents → On-call → Alert sources). When a check fails fail_after times in a row, it posts one alert through that source, exactly like an Alertmanager alert would: it pages the source's escalation policy and opens an incident if the source says so. The alert stays one page while the check keeps failing, and resolves when the check passes. The alert text names the check and its target; it goes to your on-call, not the public page. Without a source, checks still change the page and nothing pages.

A maintenance window that covers the check mutes the alert while it runs. A check that is still failing when the window ends alerts on its next run.

Maintenance

Schedule a window with a title, a message, a start and an end (up to 14 days), the services it covers (none ticked: all) and whether it mutes alerts (on by default). Upcoming and in-progress windows show on the page, and a service under maintenance says so. End one early from the row menu. Hiding a window keeps it in the console only.

Subscribers

  • RSS and Atom: /status/{slug}/rss.xml and /status/{slug}/atom.xml, with every incident update, maintenance window and changelog entry. They carry what the page shows and nothing else.
  • Webhook: a reader subscribes a URL with POST /api/status/subscribe and {"slug": "…", "url": "https://…", "components": ["Public API"]} (service names; leave it out for the whole page). The cloud first posts a verification request with a challenge; the URL must answer 2xx with the challenge in the body. The answer includes a signing secret, shown once. Deliveries are JSON (status.incident.created|updated|resolved, status.maintenance.scheduled|started|completed), signed like the org webhooks (venom-signature: t=…,v1=…), retried with backoff, and carry an unsubscribe address (DELETE it). A subscriber that fails ten deliveries in a row is dropped. At most 200 subscribers per page and 3 per host. In production the URL must be public https.
  • Email: offered on the page only while the organisation has a mail provider connected in Support settings (its own SMTP server, or its own Postmark, SendGrid, Mailgun or Resend key); the cloud has no mail account of its own. A reader enters an address (and optionally the services to follow) on the page, or POST /api/status/subscribe with {"slug": "…", "email": "…"}. Nothing is sent to it until it follows the confirmation link (GET /api/status/subscribe/confirm/{token}, valid once; an unconfirmed address is forgotten after two days). The answer is the same whether or not the address was already known. Every update mail ends with an unsubscribe link (GET /api/status/subscribe/{id}). Mails go out through the same queue and retries as webhooks.

The org's own webhooks (Settings → Webhooks) can take the same events without subscribing like a reader: status.incident.created, status.incident.updated, status.incident.resolved, status.maintenance.scheduled, status.maintenance.started and status.maintenance.completed, with what the public page shows plus the incident's or window's id, and status.component.changed when a service's automatic incident opens (down or degraded) or resolves (operational, or idle with no traffic). A hidden incident or window tells no one.

The list in Settings shows a webhook subscriber's host (never its URL) or an email subscriber's address, whether it is confirmed, and the services it follows. Remove one from the row menu.

Badge and history

  • /status/{slug}/badge.svg is an SVG you can embed: <img src="https://…/status/acme/badge.svg" alt="Status">. It shows the page's title and its state.
  • /status/{slug}/history lists the past 12 months of published incidents by month.

Admin API

Under /api/admin/v1 (the same authentication as the rest of the admin API); reads are org:read, changes org:manage, and another organisation's id is a 404.

Route What
GET /api/admin/v1/status-page/checks, POST /api/admin/v1/status-page/checks List and add checks (a heartbeat's heartbeat_url is in the answer once)
GET /api/admin/v1/status-page/checks/{id}, PATCH /api/admin/v1/status-page/checks/{id}, DELETE /api/admin/v1/status-page/checks/{id} Read, change (or rotate_token) and delete a check
GET /api/admin/v1/status-page/checks/{id}/results A check's runs, newest first (limit, before)
GET /api/admin/v1/status-page/maintenance, POST /api/admin/v1/status-page/maintenance List (state) and schedule windows
PATCH /api/admin/v1/status-page/maintenance/{id}, DELETE /api/admin/v1/status-page/maintenance/{id} Change, end early or delete a window
GET /api/admin/v1/status-page/subscribers Who follows the page (host and services only)
DELETE /api/admin/v1/status-page/subscribers/{id} Remove a subscriber
GET /api/status/heartbeat/{token} or POST /api/status/heartbeat/{token} A heartbeat's ping: the secret URL your job requests
POST /api/status/subscribe, DELETE /api/status/subscribe/{id} A reader's webhook or email subscription and unsubscribe (public)
GET /api/cron/status-checks The cron tick (CRON_SECRET); not for you to call

PUT /api/admin/v1/status-page also takes alert_source_id, and each component may carry a group.

For agents

Tools What they do
status_check_list, _get, _create, _update, _delete, _results Checks and their runs (rotate_token on update replaces a heartbeat's URL)
status_maintenance_list, _create, _update, _delete Maintenance windows
status_subscriber_list, _delete Who follows the page
status_component_list, _create, _update, _delete The services the page lists

The endpoint /workspace/mcp/status serves only these. A personal API key acts with its member's role: changes need an owner or admin; a viewer and a team key read. An OAuth app needs status:read to use the tools and status:write to change anything. Creating a heartbeat check returns its secret URL once; show it to a person and don't log it.

Troubleshooting

Symptom Cause and fix
A check says "The URL must use https" or "private address" Production only calls public https addresses. Put a daemon next to a private service, or expose a public health endpoint.
A check never runs It is paused, or the cron is not running (CRON_SECRET unset on the deployment).
Alerts don't page The page has no alert source, the source is turned off, or the organisation has no Incidents add-on. A maintenance window may be muting them.
A heartbeat fails right after creating it It waits one interval plus grace for the first ping.
A webhook subscription is refused The URL didn't echo the challenge, isn't public https, or is already subscribed.
The page has no email box The organisation has no mail provider connected in Support settings.