On-Call Management

On-call management ensures someone is always available to respond to critical alerts. Kodo helps you create schedules, rotate responsibilities, and escalate when needed.

Core Concepts

Schedules

A schedule defines who is on-call and when:

Rotation: Team members take turns being on-call
Shifts: Time periods (e.g., weekly, daily, custom)
Overrides: Temporary changes for vacations or swaps

Escalation Policies

When alerts aren’t acknowledged, escalate to the next person:

Alert Fired
    ↓ (5 min)
Primary On-Call
    ↓ (10 min, not acknowledged)
Secondary On-Call
    ↓ (15 min, not acknowledged)
Engineering Manager

Creating an On-Call Schedule

Dashboard
API

Go to Dashboard → On-Call → Create Schedule
Name your schedule (e.g., “API Team On-Call”)
Add team members
Choose rotation type:
- Weekly: Each person on-call for a week
- Daily: Rotate daily
- Custom: Define specific shifts
Set handoff time (e.g., 9:00 AM Monday)
Save schedule

curl -X POST "https://kodostatus.com/api/oncall/schedules" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Team On-Call",
    "timezone": "America/New_York",
    "rotation_type": "weekly",
    "handoff_time": "09:00",
    "handoff_day": "monday",
    "members": [
      { "user_id": "user_alice", "order": 1 },
      { "user_id": "user_bob", "order": 2 },
      { "user_id": "user_charlie", "order": 3 }
    ]
  }'

Schedule Types

Weekly Rotation

Most common for small teams:

Week 1: Alice
Week 2: Bob
Week 3: Charlie
Week 4: Alice (cycle repeats)

Follow-the-Sun

For global teams, hand off as business hours end:

US Hours (9 AM - 5 PM EST): US Team
EU Hours (9 AM - 5 PM CET): EU Team
APAC Hours (9 AM - 5 PM JST): APAC Team

Layered Schedules

Combine schedules for 24/7 coverage:

{
  "layers": [
    {
      "name": "Business Hours",
      "schedule_id": "sched_business",
      "hours": { "start": "09:00", "end": "18:00" }
    },
    {
      "name": "After Hours",
      "schedule_id": "sched_afterhours",
      "hours": { "start": "18:00", "end": "09:00" }
    }
  ]
}

Escalation Policies

Define what happens when alerts go unacknowledged:

curl -X POST "https://kodostatus.com/api/oncall/policies" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Critical Alert Escalation",
    "steps": [
      {
        "targets": [{ "type": "schedule", "id": "sched_api_team" }],
        "timeout_minutes": 5
      },
      {
        "targets": [{ "type": "user", "id": "user_eng_manager" }],
        "timeout_minutes": 10
      },
      {
        "targets": [{ "type": "channel", "id": "ch_pagerduty" }],
        "timeout_minutes": 15
      }
    ],
    "repeat_count": 2
  }'

This policy:

Notifies whoever is on-call from the API team schedule
Waits 5 minutes for acknowledgment
If not acknowledged, notifies the engineering manager
Waits 10 more minutes
If still not acknowledged, triggers PagerDuty
Repeats the entire escalation 2 more times

Escalation steps support multiple notify methods: web_push, voice_call, email, and sms. Add voice_call to automatically phone responders when alerts go unacknowledged. See Voice Alerts for setup and billing details.

Schedule Overrides

When someone needs to swap shifts or take time off: Create overrides in the Dashboard or via API:

Dashboard
API

Go to Dashboard > On-Call > Schedules
Click on a schedule and select Add Override
Choose the user, time range, and reason

curl -X POST "https://kodostatus.com/api/oncall/overrides" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "sched_api_team",
    "user_id": "user_bob",
    "start": "2024-02-15T09:00:00Z",
    "end": "2024-02-16T09:00:00Z",
    "reason": "Covering for Alice PTO"
  }'

Who’s On-Call Right Now?

Dashboard
CLI
API

View current on-call in Dashboard → On-Call → Now

kodo status

# Shows current on-call alongside service status

curl "https://kodostatus.com/api/oncall/schedules" \
  -H "X-API-Key: your_api_key"

Notification Preferences

Team members can set their notification preferences:

Push: Browser push notifications (all plans)
Voice Call: AI-powered phone calls via Voice Alerts (Team+)
SMS: Text messages for all alerts
Email: Fallback for non-urgent

Configure notification preferences in Dashboard > On-Call > Preferences or via API:

curl -X PATCH "https://kodostatus.com/api/oncall/preferences" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "critical": ["phone", "sms"],
    "major": ["sms", "push"],
    "minor": ["email"]
  }'

Best Practices

Keep rotations fair

Distribute on-call burden evenly. Consider time zones and personal situations.

Set realistic timeouts

Give people time to respond—5 minutes for critical, 15+ for major. Too short causes stress, too long delays response.

Document runbooks

Ensure on-call engineers know how to respond to common alerts.

Review escalations regularly

Analyze escalation patterns monthly. If alerts frequently escalate, investigate why.

Respect off-hours

Minimize non-critical alerts during nights and weekends.

Getting Started

Status Management

Monitoring

Alerting

Automation

Notifications

Client Tracking

Integrations

On-Call Management

Core Concepts

Schedules

Escalation Policies

Creating an On-Call Schedule

Schedule Types

Weekly Rotation

Follow-the-Sun

Layered Schedules

Escalation Policies

Schedule Overrides

Who’s On-Call Right Now?

Notification Preferences

Best Practices

​Core Concepts

​Schedules

​Escalation Policies

​Creating an On-Call Schedule

​Schedule Types

​Weekly Rotation

​Follow-the-Sun

​Layered Schedules

​Escalation Policies

​Schedule Overrides

​Who’s On-Call Right Now?

​Notification Preferences

​Best Practices

Core Concepts

Schedules

Escalation Policies

Creating an On-Call Schedule

Schedule Types

Weekly Rotation

Follow-the-Sun

Layered Schedules

Escalation Policies

Schedule Overrides

Who’s On-Call Right Now?

Notification Preferences

Best Practices