Beacon

Getting Started

Core Concepts

Beacon is built around a small set of primitives that compose into a complete status communication platform. This page explains every object in the data model and how they relate to each other.

Data model overview

The hierarchy of objects in Beacon:

Workspace
|
|-- Status Page
|   |-- Component      (API, Dashboard, Workers ...)
|   |-- Incident
|   |   |-- Incident Update
|   |-- Subscriber    (email, double opt-in)
|
|-- Monitor        (HTTP check or heartbeat)
|   |-- linked to Component + Status Page
|
|-- Team Members   (owner, admin, member roles)
|-- API Tokens
|-- Billing

Workspaces

A workspace is the top-level multi-tenant container. Everything you create in Beacon belongs to a workspace.

  • Each workspace has its own subscription, billing, and usage limits.
  • Invite team members and assign roles: owner (full control, billing), admin (manage pages, incidents, monitors), member (create/update incidents and updates).
  • A single user account can belong to multiple workspaces.
  • API tokens are scoped to a workspace -- they grant access to all pages and monitors within that workspace.

Status Pages

A status page is the public-facing representation of your service health. Each page has its own URL, set of components, incidents, and subscribers.

  • One workspace can contain multiple status pages -- useful for multi-product companies or internal vs. external pages.
  • Pages can be public (anyone can view) or private (only authenticated workspace members).
  • Each page has a configurable timezone that controls how timestamps appear to visitors.
  • Optional custom domain support via CNAME.
  • Pages expose an Atom feed and a JSON snapshot endpoint for programmatic consumers.

Components

Components are the individual services or infrastructure elements displayed on a status page. They answer the question "what is the current health of each part of our system?"

Every component has a status:

Status Meaning
operational Everything is working as expected.
degraded Performance is below normal but the service is functional.
partial_outage Some users or regions are unable to use the service.
major_outage The service is completely unavailable.
maintenance The service is undergoing scheduled maintenance.
unknown Status has not been determined (default for new unmonitored components).

Components can be reordered in the dashboard. The order is reflected on the public status page.

Incidents

An incident is a record of an event that affects the status of one or more components. Incidents appear on the public status page and trigger subscriber notifications.

Impact levels

Impact When to use
none Informational notice with no user-visible impact.
minor Small subset of users affected or non-critical feature degraded.
major Significant functionality impaired for a large portion of users.
critical Complete service outage or data integrity issue.

State transitions

Every incident moves through a lifecycle:

investigating  -->  identified  -->  monitoring  -->  resolved
  • Investigating — The team is looking into the issue. This is the default starting state.
  • Identified — Root cause has been found and a fix is in progress.
  • Monitoring — A fix has been deployed and the team is confirming stability.
  • Resolved — The issue is fully fixed. The incident is moved to history.

Incident Updates

Each incident has a timeline of updates. An update is a timestamped message that describes what changed since the last communication. Updates are displayed in reverse chronological order on the public page.

When you create an incident with an initial message, that message becomes the first update automatically. Subsequent updates can be posted via the dashboard or the API.

Monitors

Monitors are automated checks that verify your services are running. Beacon supports two monitor types:

  • HTTP monitors — Beacon pings a URL at a configurable interval and checks for a successful response (2xx status code). If the check fails for a configured number of consecutive attempts, Beacon automatically creates an incident.
  • Heartbeat monitors — Your service sends periodic pings to a unique Beacon URL. If a ping is not received within the expected window, an incident is created. Ideal for cron jobs, background workers, and batch processes.

Monitors are linked to a specific component and status page. When a monitor detects a failure, it sets the component status and creates an incident on the linked page. When the service recovers, the monitor automatically resolves the incident and restores the component to operational.

Subscribers

Subscribers are users who sign up to receive email notifications when incidents are created or updated on a status page.

  • Subscription uses a double opt-in flow: the user enters their email on the public page, receives a confirmation link, and must click it to activate.
  • Notifications are sent when a new incident is created and when an incident receives an update.
  • Every notification includes a one-click unsubscribe link.
  • Subscriber limits vary by plan.

Where to go next