Documentation · OutageBeacon

Mental model

Think of the product as four layers. Each layer feeds the next one.

1. Watch

Monitors

Scheduled checks for websites, APIs, ports, certificates, domains, pings, UDP, and AI model probes.

2. Detect

Incidents

A failing monitor opens an incident. Recovery resolves it. You can acknowledge, resolve, and add a postmortem.

3. Notify

Channels

Email and integrations receive alerts. Channels can be tested, snoozed, and quieted during a time window.

4. Communicate

Status pages

Customer-facing pages show components, history, timeline updates, feeds, embeds, and subscriber delivery.

Recommended first setup

If you want uptime monitoring

Create a monitor from /monitors/new.
Add at least one notification channel from /channels/new.
Open the monitor detail page to confirm checks are running.
Create a status page and attach the monitor if customers should see it.

If you want error tracking

Create an Errors project from /errors/projects/new.
Copy the DSN key from the project detail page.
Install the SDK or send events to the ingest endpoint.
Use Issues, Tags, Releases, Ownership, and Alerts to triage events.

Dashboard map

The authenticated dashboard lives behind login. /dashboard redirects to Monitors because monitors are the main operating surface.

Page	URL	What it is for
Monitors	/monitors	Create, group, reorder, pause, and inspect uptime checks.
Heartbeats	/heartbeats	Track cron jobs and background tasks that must call back on schedule.
Incidents	/incidents	Review open and closed incidents, acknowledge alerts, resolve issues, and write postmortems.
Status pages	/status_pages	Build customer-facing pages with components, updates, audiences, integrations, and subscribers.
Channels	/channels	Configure alert delivery to email, chat, webhook, paging, push, or SMS destinations.
Maintenance	/maintenance	Schedule planned downtime so noisy checks do not surprise you.
Errors	/errors/projects	Create error-tracking projects, inspect issues, upload source maps, and configure alert rules.
Onboarding	/onboarding	See workspace setup progress after signup or whenever a workspace needs a first-pass setup review.
API tokens	/tokens	Generate bearer tokens for the REST API.
Billing	/billing	See plan state, checkout availability, and Stripe portal links when billing is configured.
Team	/team	Invite teammates by token, manage roles, cancel pending invites, and transfer the primary owner.
Workspaces	/workspaces	Switch between orgs when one account belongs to multiple teams or products.
Launch	/admin/launch	Owner/admin readiness checklist for runtime, email, billing, probe, status-page, legal, and operations checks.

Monitoring

A monitor is one scheduled check. The scheduler assigns checks to workers, results are stored, and monitor status changes can open or resolve incidents.

Monitor types

HTTP / HTTPS: checks a URL and validates expected response codes.
HTTP + keyword: checks a URL and validates text presence or absence.
API: HTTP checks with custom method, headers, body, JSON, and expected codes.
Ping: ICMP reachability for a host.
Port and UDP: network checks for host:port targets.
SSL certificate: certificate expiry tracking.
Domain expiry: WHOIS/domain expiration tracking.
AI model: probes model availability, time to first token, total latency, and tokens per second.

Monitor status

Unknown: created, but no usable check result yet.
Up: the latest result matched the configured success criteria.
Slow: reachable, but response time crossed the slow threshold.
Down: failed check, failed assertion, expired certificate, missed heartbeat, or network failure.
Paused: intentionally not checked until resumed.

Heartbeats are different

A heartbeat is not polled by OutageBeacon. Your job calls /hb/<token>. If the system does not receive a ping inside the configured period plus grace window, the heartbeat turns down and can alert through attached channels.

Status pages

Status pages turn internal monitor and incident state into customer-facing communication. A page can include monitors, third-party dependencies, manual timeline updates, subscribers, RSS/Atom feeds, embeds, and API output.

Components

Components are the things shown on the public page. They can be attached monitors or external dependencies. You can rename, group, and reorder them.

Updates

Updates are timeline entries like investigating, identified, monitoring, resolved, maintenance, or notice. Incident automation can create drafts for operators to publish.

Audiences

Audience pages let one status page expose different component sets to different customer groups or internal viewers.

Public surface	URL pattern	Purpose
Status page	/s/{slug}	Main public page for uptime and active incidents.
History	/s/{slug}/history	Past incidents and updates.
Component detail	/s/{slug}/components/{id}	Per-component history and uptime details.
JSON status API	/api/status/{slug}	Machine-readable status output.
RSS / Atom	/s/{slug}/feed.rss	Subscribe to timeline updates in feed readers.
Embed script	/s/{slug}/embed.js	Small status indicator for external sites.

Notifications and incident flow

Channels are reusable alert destinations. Monitors and heartbeats can attach explicit channels; if no channel is attached, alerts fall back to the org owner email path.

Channel types

Email, Slack, Discord, generic webhook, Microsoft Teams, Mattermost, Telegram, PagerDuty, Pushover, and SMS.

Controls

Each channel can be tested, deleted, snoozed for a fixed duration, or configured with quiet hours. Quiet hours drop notifications in that window instead of queueing them.

Incident lifecycle

A check failure can open an incident, send a down alert, and draft status-page communication. A recovery check resolves the incident and can send recovery alerts and status-page subscriber updates. Operators can acknowledge, resolve, and add postmortem text from the incident detail page.

Errors module

The Errors module is Sentry-style application error tracking. Projects receive events through a DSN, group them into issues, and expose triage tools.

Core pages

Projects: container for DSN keys and issue grouping.
Issues: grouped exceptions with status, priority, comments, assignee, and event details.
Releases: release-oriented event context.
Tags: searchable dimensions extracted from events.
User feedback: comments submitted by end users through the feedback endpoint.

Configuration pages

Alerts: rules for when error events should notify channels.
Teams: internal groups for ownership and assignment.
Ownership: route issues to users or teams based on project rules.
Source maps: upload artifacts for better JavaScript stack traces.
Processing: filters, scrubbing, fingerprint rules, and org-level event limits.

SDK docs

Error projects include platform-specific setup snippets on the project detail page. Create a project, copy a DSN key, choose the closest platform, and send one test event before shipping the SDK to production.

Browser and frontend

Use the browser SDK for plain JavaScript or framework wrappers for React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, Astro, Remix, Gatsby, Ember, and Electron.

<script src="https://<host>/static/outagebeacon.js"></script>
<script>
  OutageBeacon.init({
    dsn: "<dsn>",
    environment: "production",
    release: "v1.0.0"
  });
</script>

Node and server JavaScript

Use the Node SDK directly or framework snippets for Express, Koa, Fastify, NestJS, Bun, Deno, Cloudflare Workers, and serverless functions.

npm install outagebeacon

const outagebeacon = require("outagebeacon");
outagebeacon.init({ dsn: "<dsn>", environment: "production" });
outagebeacon.installGlobalHandlers();

Python

Use the Python SDK for scripts and the framework snippets for Django, Flask, FastAPI, Starlette, Tornado, Celery, and AWS or GCP functions.

pip install outagebeacon

import outagebeacon
outagebeacon.init(dsn="<dsn>", environment="production")
outagebeacon.install_excepthook()

Backend and native

Project snippets cover Go, Ruby, Rails, PHP, Laravel, Java, Spring Boot, .NET, Elixir, Phoenix, Rust, Android, iOS, macOS, React Native, Flutter, Unity, Unreal, Godot, Qt, and Cordova.

go get github.com/outagebeacon/outagebeacon-go

c, _ := outagebeacon.New(outagebeacon.Options{
    DSN: "<dsn>",
    Environment: "production",
})

Verification checklist

Create one project per app or service.
Use separate DSN keys for staging and production when you need independent revocation.
Set environment and release during initialization.
Send one test exception and confirm it appears on the project Issues page.
Add source maps or release metadata before relying on JavaScript stack traces.

API and tokens

API tokens are generated from /tokens. Send them as bearer tokens. The current REST API is intentionally narrow.

curl https://<your-host>/v1/monitors \
  -H "Authorization: Bearer YOUR_TOKEN"

Method	Endpoint	Use
GET	/v1/health	Authenticated health check for API clients.
GET	/v1/monitors	List monitors visible to the token's org.
POST	/v1/monitors	Create a monitor.
DELETE	/v1/monitors/{id}	Delete a monitor.

API requests are rate limited. Public status-page JSON and heartbeat endpoints do not use these API tokens; they use their own public slug or heartbeat token model.

Billing and plan gates

Billing controls monitor limits, interval limits, channel availability, API token access, status-page limits, and advanced monitoring controls. The app renders internal plan value solo as Starter.

Free

20 monitors, 5-minute interval, one public status page, email alerts, and no public API tokens.

Starter

50 monitors, 60-second interval, advanced HTTP options, groups, SSL/domain checks, multi-region, subscribers, custom domains, and API tokens.

Team and above

Higher limits, more seats, paging/SMS channels, audit-oriented status-page views, and additional operating capacity.

Glossary

Org: The workspace that owns users, monitors, status pages, channels, billing, and API tokens.
Workspace: The selected org whose resources the dashboard currently shows.
Monitor: A scheduled check against one target.
Check result: One execution result from a monitor, including region, success/failure, status code, latency, and error text.
Incident: A tracked outage or degradation window tied to a monitor.
Channel: A delivery destination for alerts.
Status page: A public or protected page that communicates component health and incident updates.
DSN: The project-specific key and ingest URL used by error-tracking SDKs.
Invite token: A time-limited team link that lets a matching email address join a workspace.
API token: A bearer token used for authenticated REST API calls.

How the website fits together

Mental model

Monitors

Incidents

Channels

Status pages

Recommended first setup

If you want uptime monitoring

If you want error tracking

Dashboard map

Monitoring

Monitor types

Monitor status

Heartbeats are different

Status pages

Components

Updates

Audiences

Notifications and incident flow

Channel types

Controls

Incident lifecycle

Errors module

Core pages

Configuration pages

SDK docs

Browser and frontend

Node and server JavaScript

Python

Backend and native

Verification checklist

API and tokens

Billing and plan gates

Free

Starter

Team and above

Glossary

Are you sure?

Enter a value