Incidents

Track outages as incidents that open when a monitor goes down and close on recovery.

An incident records a period of downtime for a monitor. Incidents are created and resolved automatically, so they are the raw material behind your uptime numbers and the timeline you show on a status page.

How incidents are created

A background worker watches each monitor's heartbeat window. When a monitor misses its expected interval plus grace period, the worker opens an incident. The incident stays active while the monitor is down. When a recovering heartbeat arrives, the worker resolves the incident and records its end time.

Lifecycle

A resolved incident captures how long the outage lasted, which feeds directly into your uptime percentage and downtime totals.

Listing incidents

Fetch the incident history for a monitor, most recent first:

const incidents = await vanta.uptime.getIncidents('mon_abc123')

for (const incident of incidents) {
  console.log(incident.status, incident.startedAt, incident.durationMs)
}

Describing incidents

Give an incident a title and description so you can record what actually happened. You can edit an incident any time, including while it is still active:

await vanta.uptime.updateIncident({
  incidentId: 'inc_abc123',
  data: {
    title: 'Database connection pool exhausted',
    description: 'Read replicas fell behind and the API returned 503s for about 40 minutes.',
  },
})

Either field is optional, but at least one is required. Setting a field to an empty string clears it. Incidents that have no title or description are rendered as a plain timeline entry.

Edge cases

• Heartbeats that arrive while an incident is active do not create new incidents; they resolve the current one.
• A paused monitor is not evaluated, so pausing does not open an incident even if heartbeats stop.
• Deleting a monitor deletes its incidents along with the monitor.
• Incident resolution is driven by the next heartbeat, so a monitor that recovers in the middle of its window resolves promptly rather than waiting for the next scheduled check.