> ## 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.

# On-Call Management

> Schedule on-call rotations and escalation policies

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

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Dashboard → On-Call → Create Schedule**
    2. Name your schedule (e.g., "API Team On-Call")
    3. Add team members
    4. Choose rotation type:
       * **Weekly**: Each person on-call for a week
       * **Daily**: Rotate daily
       * **Custom**: Define specific shifts
    5. Set handoff time (e.g., 9:00 AM Monday)
    6. Save schedule
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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 }
        ]
      }'
    ```
  </Tab>
</Tabs>

## 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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

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

<Info>
  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](/alerting/voice-alerts) for setup and billing details.
</Info>

## Schedule Overrides

When someone needs to swap shifts or take time off:

Create overrides in the Dashboard or via API:

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Dashboard > On-Call > Schedules**
    2. Click on a schedule and select **Add Override**
    3. Choose the user, time range, and reason
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

## Who's On-Call Right Now?

<Tabs>
  <Tab title="Dashboard">
    View current on-call in **Dashboard → On-Call → Now**
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    kodo status

    # Shows current on-call alongside service status
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl "https://kodostatus.com/api/oncall/schedules" \
      -H "X-API-Key: your_api_key"
    ```
  </Tab>
</Tabs>

## Notification Preferences

Team members can set their notification preferences:

* **Push**: Browser push notifications (all plans)
* **Voice Call**: AI-powered phone calls via [Voice Alerts](/alerting/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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Keep rotations fair">
    Distribute on-call burden evenly. Consider time zones and personal situations.
  </Accordion>

  <Accordion title="Set realistic timeouts">
    Give people time to respond—5 minutes for critical, 15+ for major. Too short causes stress, too long delays response.
  </Accordion>

  <Accordion title="Document runbooks">
    Ensure on-call engineers know how to respond to common alerts.
  </Accordion>

  <Accordion title="Review escalations regularly">
    Analyze escalation patterns monthly. If alerts frequently escalate, investigate why.
  </Accordion>

  <Accordion title="Respect off-hours">
    Minimize non-critical alerts during nights and weekends.
  </Accordion>
</AccordionGroup>