Incident Safeguards

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.

Dashboard
API

When creating or editing a monitor:

Go to Dashboard > Uptime > Add Monitor
Under Incident Safeguards, set Failure threshold
The monitor must fail this many times in a row before an incident is created

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
  }'

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

Dashboard
API

In the monitor creation/edit dialog, set Cooldown (minutes) under Incident Safeguards.

curl -X PATCH "https://kodostatus.com/api/v1/uptime-monitors/mon_abc" \
  -H "X-API-Key: your_api_key" \
  -d '{"incident_cooldown_seconds": 1800}'

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.

Draft Mode

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

Dashboard
How It Works

Go to Settings > Automation
Set Auto-incident visibility to Create as draft
Optionally set an Auto-publish delay (e.g., 5 minutes)

Auto-Publish

If you want a review window without manual intervention:

Set visibility to Create as draft
Set Auto-publish delay to your desired review window (e.g., 5 minutes)
Draft incidents will automatically become public after the delay
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.

Dashboard
How It Works

Go to Settings > Automation
Set Notification batch window (in seconds)

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:

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 for higher limits.

Recommended Configuration

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.

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.

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.

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

Getting Started

Status Management

Monitoring

Alerting

Automation

Notifications

Client Tracking

Integrations

Incident Safeguards

How Auto-Created Incidents Work

The Safeguard Pipeline

Flap Protection

Cooldown Period

Maintenance Window Awareness

Draft Mode

Auto-Publish

Notification Batching

Severity Override

Incident Source Tracking

Dedup Protection

Plan Limits

Recommended Configuration

Where Settings Live

​How Auto-Created Incidents Work

​The Safeguard Pipeline

​Flap Protection

​Cooldown Period

​Maintenance Window Awareness

​Draft Mode

​Auto-Publish

​Notification Batching

​Severity Override

​Incident Source Tracking

​Dedup Protection

​Plan Limits

​Recommended Configuration

​Where Settings Live

How Auto-Created Incidents Work

The Safeguard Pipeline

Flap Protection

Cooldown Period

Maintenance Window Awareness

Draft Mode

Auto-Publish

Notification Batching

Severity Override

Incident Source Tracking

Dedup Protection

Plan Limits

Recommended Configuration

Where Settings Live