Incidents

---
name: "Better Stack Incidents"
description: >
  Better Stack incidents: incident records raised by uptime monitors or
  reported manually, and the triage, acknowledgment, and resolution
  lifecycle.
when_to_use: >-
  When listing, triaging, acknowledging, or resolving Better Stack
  incidents. Use when: betterstack incident, incident triage, incident
  acknowledgment, incident resolution, acknowledge incident, resolve
  incident, downtime incident, or better stack incident.
---

# Better Stack Incidents

## Overview

Incidents in Better Stack are triggered automatically when uptime monitors detect downtime, or created manually for ad-hoc issues. Each incident tracks the timeline from detection through acknowledgment to resolution, with associated monitors, status page updates, and on-call notifications.

## Anti-triggers

- **A security incident** — Better Stack incidents are uptime events
  with no threat model, no indicators, and no remediation flow; use
  `huntress-incidents`.
- **The MSP's major-incident process** — if the question is about
  incident commanders, customer comms, or postmortems rather than a
  failing check, use `rootly-incidents` or `pagerduty-incidents`.
- **Billable follow-up work** — an incident is not a PSA ticket; use
  `autotask`, `halopsa`, or `connectwise-psa`.
- **Telling end users about the outage** — use
  `betterstack-status-pages`.

## Key Concepts

### Incident Lifecycle

1. **Triggered** - Monitor detects downtime and creates an incident
2. **Acknowledged** - On-call responder acknowledges the incident
3. **Resolved** - The issue is fixed and the incident is closed
4. **Auto-resolved** - Monitor detects recovery and automatically resolves

### Incident Attributes

- **Started at** - When the incident was first detected
- **Acknowledged at** - When a responder acknowledged
- **Resolved at** - When the incident was resolved
- **Cause** - The monitor or manual source that triggered it
- **Call** - Whether a phone call alert was triggered
- **SMS** - Whether an SMS alert was sent
- **Email** - Whether an email alert was sent

### Incident Severity

Better Stack does not enforce severity levels on incidents directly -- severity is determined by the monitor's configuration and escalation policy. However, incidents from monitors with shorter check intervals and immediate escalation are implicitly higher priority.

## API Patterns

### List Incidents

```
betterstack_list_incidents
```

Parameters:
- `page` - Pagination cursor
- `per_page` - Results per page
- `from` - Start date filter (ISO 8601)
- `to` - End date filter (ISO 8601)

**Example response:**

```json
{
  "data": [
    {
      "id": "67890",
      "type": "incident",
      "attributes": {
        "name": "Example Website is down",
        "cause": "HTTP 503 Service Unavailable",
        "started_at": "2026-03-27T08:15:00Z",
        "acknowledged_at": null,
        "resolved_at": null,
        "call": true,
        "sms": true,
        "email": true
      },
      "relationships": {
        "monitor": {
          "data": { "id": "12345", "type": "monitor" }
        }
      }
    }
  ]
}
```

### Get Incident Details

```
betterstack_get_incident
```

Parameters:
- `incident_id` - The incident ID

### Acknowledge Incident

```
betterstack_acknowledge_incident
```

Parameters:
- `incident_id` - The incident ID

### Resolve Incident

```
betterstack_resolve_incident
```

Parameters:
- `incident_id` - The incident ID

## Common Workflows

### Daily Incident Triage

1. Call `betterstack_list_incidents` with date filters for the current period
2. Identify unacknowledged incidents (acknowledged_at is null)
3. Group incidents by monitor to identify patterns
4. Acknowledge incidents that are being investigated
5. Resolve incidents that have auto-recovered

### Incident Investigation

1. Get incident details with `betterstack_get_incident`
2. Identify the associated monitor and check its current status
3. Review the incident timeline (started, acknowledged, resolved)
4. Check if the monitor has recovered or is still down
5. Cross-reference with logs using `betterstack_query_logs`
6. Acknowledge the incident if actively investigating
7. Resolve once the root cause is addressed

### Post-Incident Review

1. List incidents for the review period
2. Calculate mean time to acknowledge (MTTA) and mean time to resolve (MTTR)
3. Identify monitors with recurring incidents
4. Review escalation policy effectiveness
5. Update monitors and alerts based on findings

## Error Handling

### Incident Not Found

**Cause:** Invalid incident ID or incident was deleted
**Solution:** List incidents to verify the correct ID

### Incident Already Resolved

**Cause:** Attempting to acknowledge or resolve an already-resolved incident
**Solution:** Check incident status before taking action

### Incident Already Acknowledged

**Cause:** Attempting to acknowledge an already-acknowledged incident
**Solution:** Proceed to resolve if the issue is fixed

## Best Practices

- Acknowledge incidents promptly to stop escalation chains
- Use date filters to scope incident lists to relevant periods
- Track MTTA and MTTR metrics per client for SLA compliance
- Cross-reference incidents with log data for root cause analysis
- Set up auto-resolve so monitors close incidents when services recover
- Review recurring incidents to identify systemic issues
- Create PSA tickets for incidents requiring follow-up work

## Related Skills

- [api-patterns](../api-patterns/SKILL.md) - Pagination and error handling
- [monitors](../monitors/SKILL.md) - Monitors that trigger incidents
- [status-pages](../status-pages/SKILL.md) - Status page incident updates
- [oncall](../oncall/SKILL.md) - On-call notifications for incidents
- [logging](../logging/SKILL.md) - Log investigation during incidents