Alerts Overview

Alerts are incidents received via webhooks from your monitoring systems. They have a severity level (critical, high, medium, low, info), flow through relays, and can be responded to, assigned, and resolved.

Alert Lifecycle

1. Created: Alert is received via webhook or integration
2. Routed: Alert flows through relay rules
3. Notified: On-call users are notified via their contact methods
4. Responded: One or more responders signal they’re on it
5. Assigned: Alert is assigned to a specific user (optional)
6. Resolved: Alert is marked as resolved

Multiple responders can join the same alert. Each responder tracks their own status (on_it, done, dropped) independently.

Alert Severity Levels

Alerts have five severity levels:

• Critical: Immediate attention required, service down
• High: Important issue requiring prompt attention
• Medium: Non-urgent issue that should be addressed
• Low: Minor issue with minimal impact
• Info: Informational notification, no action required

const alerts = await client.alert.list();

const criticalAlerts = alerts.filter((a) => a.severity === "critical");
console.log(`${criticalAlerts.length} critical alerts`);

Alert States

Active Alerts

Alerts that haven’t been resolved:

const activeAlerts = await client.alert.listActive();
console.log(`${activeAlerts.length} alerts need attention`);

Resolved Alerts

Alerts that have been resolved:

const resolvedAlerts = await client.alert.listResolved();
console.log(`${resolvedAlerts.length} alerts resolved`);

Common Operations

Responding to an Alert

Signal that you’re working on an alert:

const responder = await client.alert.onIt("alr_abc123", {
  userId: "usr_alice",
});

console.log(`${responder.userId} is on it (joined ${responder.joinedAt})`);

Assigning an Alert

Assign an alert to a specific user:

const assigned = await client.alert.assign("alr_abc123", "usr_bob");
console.log(`Assigned to ${assigned.assignedToUserId}`);

Resolving an Alert

Mark an alert as resolved:

const resolved = await client.alert.resolve("alr_abc123");
console.log(`Resolved at ${resolved.resolvedAt}`);

Alert Metadata

Alerts can include arbitrary metadata for context:

const alert = await client.alert.get("alr_abc123");

console.log("Alert metadata:", alert.metadata);
// Example: { server: "web-01", region: "us-west", errorRate: 15.3 }

Common Use Cases

Monitoring Active Alerts

const active = await client.alert.listActive();

console.log(`Active Alerts: ${active.length}\n`);

active.forEach((alert) => {
  console.log(`[${alert.severity.toUpperCase()}] ${alert.title}`);
  console.log(`  Source: ${alert.source}`);
  if (alert.assignedToUserId) {
    console.log(`  Assigned to: ${alert.assignedToUserId}`);
  }
  console.log();
});

On-Call Dashboard

const active = await client.alert.listActive();
const byUser = new Map<string, number>();

active.forEach((alert) => {
  if (alert.assignedToUserId) {
    const count = byUser.get(alert.assignedToUserId) || 0;
    byUser.set(alert.assignedToUserId, count + 1);
  }
});

console.log("Alerts by User:");
byUser.forEach((count, userId) => {
  console.log(`${userId}: ${count} alerts`);
});

Alert Workflow

const alertId = "alr_abc123";
const userId = "usr_alice";

const alert = await client.alert.get(alertId);
console.log(`Working on: ${alert.title}`);

const responder = await client.alert.onIt(alertId, { userId });
console.log("On it");

await client.alert.assign(alertId, userId);
console.log("Assigned to self");

console.log("Investigating...");

await client.alert.updateResponderStatus(alertId, responder.id, {
  status: "done",
});
console.log("Responder done");

await client.alert.resolve(alertId);
console.log("Resolved");