> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident Safeguards

> Prevent false incidents from reaching your public status page with flap protection, draft mode, cooldowns, and notification batching

When monitors detect failures, Kodo can automatically create incidents. Without safeguards, a single transient network blip would create a public incident and email all your subscribers. Incident safeguards prevent that.

## How Auto-Created Incidents Work

Kodo creates incidents automatically from four sources:

| Source                | Trigger                                          | Default Severity         |
| --------------------- | ------------------------------------------------ | ------------------------ |
| **Uptime Monitor**    | HTTP endpoint fails consecutive checks           | Major                    |
| **Heartbeat Monitor** | Expected heartbeat not received                  | Minor                    |
| **Integration**       | Third-party service degrades (e.g., AWS, Stripe) | Based on provider status |
| **Beacon**            | Client error rate exceeds threshold              | Major or Critical        |

Each source passes through the same safeguard pipeline before an incident is created.

## The Safeguard Pipeline

Every auto-incident request goes through these checks in order. If any check fails, the incident is **not** created.

```
Monitor failure detected
        |
        v
  1. Maintenance window? -----> Skip (service under maintenance)
        |
        v
  2. Plan limit reached? -----> Skip (monthly limit hit)
        |
        v
  3. Duplicate exists? -------> Skip (active incident for same monitor)
        |
        v
  4. Cooldown active? --------> Skip (too soon after last incident)
        |
        v
  5. Create incident
     - Apply visibility (draft or public)
     - Schedule auto-publish if configured
     - Send or batch notifications
```

## Flap Protection

Prevents incidents from transient failures. A monitor must fail **consecutively** before an incident is created.

<Tabs>
  <Tab title="Dashboard">
    When creating or editing a monitor:

    1. Go to **Dashboard > Uptime > Add Monitor**
    2. Under **Incident Safeguards**, set **Failure threshold**
    3. The monitor must fail this many times in a row before an incident is created
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://kodostatus.com/api/v1/uptime-monitors" \
      -H "X-API-Key: your_api_key" \
      -d '{
        "name": "API Health",
        "url": "https://api.example.com/health",
        "consecutive_failure_threshold": 3
      }'
    ```
  </Tab>
</Tabs>

| Threshold   | Behavior                                  |
| ----------- | ----------------------------------------- |
| 1           | Incident on first failure (no protection) |
| 3 (default) | Must fail 3 times in a row                |
| 5           | Conservative - good for flaky endpoints   |

The counter resets to 0 when the monitor returns to "up".

## Cooldown Period

Prevents duplicate incidents when a service is intermittently failing. After an incident is created for a monitor, no new incident can be created for that monitor until the cooldown expires.

Configure per monitor:

| Setting                     | Default      | Description                        |
| --------------------------- | ------------ | ---------------------------------- |
| `incident_cooldown_seconds` | 900 (15 min) | Minimum gap between auto-incidents |

<Tabs>
  <Tab title="Dashboard">
    In the monitor creation/edit dialog, set **Cooldown (minutes)** under **Incident Safeguards**.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X PATCH "https://kodostatus.com/api/v1/uptime-monitors/mon_abc" \
      -H "X-API-Key: your_api_key" \
      -d '{"incident_cooldown_seconds": 1800}'
    ```
  </Tab>
</Tabs>

## Maintenance Window Awareness

If a service is currently under a scheduled maintenance window, auto-incidents will **not** be created for monitors linked to that service. This prevents expected downtime from generating false alerts.

No configuration needed -- this works automatically based on your [scheduled maintenances](/status-management/maintenance).

## Draft Mode

By default, auto-created incidents are immediately visible on your public status page. Draft mode lets you review them first.

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Settings > Automation**
    2. Set **Auto-incident visibility** to **Create as draft**
    3. Optionally set an **Auto-publish delay** (e.g., 5 minutes)
  </Tab>

  <Tab title="How It Works">
    When draft mode is enabled:

    * Auto-created incidents are **not** visible on the public status page
    * They appear in your dashboard with a **Draft** badge
    * Subscriber notifications are **held** until the incident is published
    * You can **Publish** manually from the incidents dashboard
    * Or let them auto-publish after your configured delay
  </Tab>
</Tabs>

### Auto-Publish

If you want a review window without manual intervention:

1. Set visibility to **Create as draft**
2. Set **Auto-publish delay** to your desired review window (e.g., 5 minutes)
3. Draft incidents will automatically become public after the delay
4. Subscriber notifications are sent when the incident is published

Set the delay to **0** to keep drafts until you manually publish them.

## Notification Batching

When multiple incidents fire in quick succession, batching coalesces them into a single summary notification instead of bombarding subscribers.

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Settings > Automation**
    2. Set **Notification batch window** (in seconds)
  </Tab>

  <Tab title="How It Works">
    * Notifications are queued for the batch window duration
    * If 1 incident fires, a normal notification is sent after the window
    * If 2+ incidents fire within the window, a single summary notification lists all of them
    * Set to **0** for immediate notifications (default, backward compatible)
  </Tab>
</Tabs>

| Window | Behavior                            |
| ------ | ----------------------------------- |
| 0      | Immediate notification per incident |
| 60     | Batch incidents within 1 minute     |
| 300    | Batch incidents within 5 minutes    |

## Severity Override

Each monitor can override the default severity for auto-created incidents:

| Setting            | Effect                                          |
| ------------------ | ----------------------------------------------- |
| **Auto** (default) | Uptime monitors use Major, Heartbeats use Minor |
| **Minor**          | Low-impact incidents                            |
| **Major**          | Significant user impact                         |
| **Critical**       | Complete outage                                 |

Configure this per monitor in the **Incident Safeguards** section of the monitor dialog, or via API:

```bash theme={null}
curl -X PATCH "https://kodostatus.com/api/v1/uptime-monitors/mon_abc" \
  -H "X-API-Key: your_api_key" \
  -d '{"auto_incident_severity": "critical"}'
```

## Incident Source Tracking

Every incident records where it came from:

| Source             | Meaning                                   |
| ------------------ | ----------------------------------------- |
| `manual`           | Created by a team member in the dashboard |
| `api`              | Created via the API                       |
| `auto_uptime`      | Created by an uptime monitor              |
| `auto_heartbeat`   | Created by a heartbeat monitor            |
| `auto_integration` | Created by a third-party integration      |
| `auto_beacon`      | Created by client error rate detection    |

Filter incidents by source in **Dashboard > Incidents** using the source dropdown.

## Dedup Protection

Kodo will not create a duplicate incident for a monitor that already has an active (non-resolved) incident. This uses a direct link between the monitor and the incident -- not title matching -- so it's reliable even if incident titles change.

## Plan Limits

Auto-created incidents count toward your monthly incident limit. If you've reached the limit, auto-creation is silently skipped. [Upgrade your plan](https://kodostatus.com/dashboard/settings) for higher limits.

## Recommended Configuration

<AccordionGroup>
  <Accordion title="Low-noise production monitoring">
    * Failure threshold: **3**
    * Cooldown: **15 minutes**
    * Visibility: **Create as draft**
    * Auto-publish delay: **5 minutes**
    * Batch window: **60 seconds**

    This gives you time to verify incidents are real before they go public, and coalesces rapid-fire failures into a single notification.
  </Accordion>

  <Accordion title="Fast public alerting">
    * Failure threshold: **2**
    * Cooldown: **5 minutes**
    * Visibility: **Publish immediately**
    * Batch window: **0** (immediate)

    For teams that want fast transparency. The low threshold means quicker detection but more risk of false positives.
  </Accordion>

  <Accordion title="Conservative / high-traffic">
    * Failure threshold: **5**
    * Cooldown: **30 minutes**
    * Visibility: **Create as draft**
    * Auto-publish delay: **0** (manual only)
    * Batch window: **300 seconds**

    Best for endpoints with known flakiness. Drafts stay until a human reviews them.
  </Accordion>
</AccordionGroup>

## Where Settings Live

| Setting               | Location                                                         |
| --------------------- | ---------------------------------------------------------------- |
| Failure threshold     | Per monitor: **Uptime > Add/Edit Monitor > Incident Safeguards** |
| Cooldown period       | Per monitor: **Uptime > Add/Edit Monitor > Incident Safeguards** |
| Severity override     | Per monitor: **Uptime > Add/Edit Monitor > Incident Safeguards** |
| Draft vs. public      | Organization-wide: **Settings > Automation**                     |
| Auto-publish delay    | Organization-wide: **Settings > Automation**                     |
| Notification batching | Organization-wide: **Settings > Automation**                     |
| Maintenance windows   | Per maintenance: **Maintenance > Create**                        |