Alerts

What gets alerted

CapyDB continuously evaluates two gauges per project against the plan's limits:

There is at most one open alert per project and kind. Severity moves in place on the open alert; a resolved alert closes and a future breach opens a new one.

Thresholds and hysteresis

The trigger and resolve thresholds are deliberately apart (hysteresis), so usage hovering at exactly 80% cannot flap an alert open and closed on every evaluation sweep.

Notification rules

• A new alert notifies immediately.
• An escalation (warning → critical) notifies immediately.
• An alert that simply stays open re-notifies at most once every 24 hours.
• Resolution sends one alert.resolved notification.

Delivery channels

1. Dashboard — open alerts surface on the project, alongside the Observability gauges that triggered them.

2. Webhooks — your org's webhook endpoints receive alert.triggered and alert.resolved events (standard signed envelope):

   {
     "id": "evt_...",
     "type": "alert.triggered",
     "created_at": "2026-06-10T08:00:00.000Z",
     "data": {
       "alert_id": "alr_...",
       "kind": "storage",
       "severity": "critical",
       "observed_value": 4928307200,
       "limit_value": 5368709120,
       "project_id": "prj_...",
       "triggered_at": "2026-06-10T08:00:00.000Z"
     }
   }

   alert.resolved carries the same data plus resolved_at. Values are bytes for storage and a connection count for connections.

3. Email — when your organization has a billing email configured, alert notifications also go there as plain text. No billing email, no email; webhooks and the dashboard still work.

Acknowledging

Acknowledging records that a human has seen the alert — acknowledged_at is set once (first acknowledgement wins) and the dashboard renders it as seen. It is visual only: an acknowledged alert keeps re-notifying on the 24-hour cadence until usage actually drops and it resolves. The way to silence an alert is to fix the usage or raise the limit.

API

# Open alerts plus alerts resolved in the last 30 days
GET  /v1/projects/{projectID}/alerts

# Mark one as seen (idempotent)
POST /v1/projects/{projectID}/alerts/{alertID}/acknowledge

Both are available to any org member. See the Observability API reference for the full ProjectAlert shape.

CLI

capydb alerts list                  # uses the linked project; --project to target another
capydb alerts ack alr_123abc        # acknowledge by id
capydb alerts list --output json    # machine-readable, lists always [] not null

When an alert fires

• Storage: delete unused data, VACUUM, or move up a plan. Remember that imports are blocked when the source exceeds the plan limit anyway — the alert is your early warning before that wall.
• Connections: app traffic belongs on the pooled URL; hunt for oversized client-side pools and long-idle direct sessions. See Connection pooling.