Working with On-Call Scheduling

Get On-Call Calendars

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import OnCallCalendar

api = UptimeAPI("your-token")

for calendar in OnCallCalendar.get_all_instances(api):
    print(f"Calendar: {calendar.name or 'Default'}")
    print(f"  Team: {calendar.team_name}")
    print(f"  Default: {calendar.default_calendar}")

Get Current On-Call Users

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import OnCallCalendar

api = UptimeAPI("your-token")

for calendar in OnCallCalendar.get_all_instances(api):
    print(f"Calendar: {calendar.team_name}")

    # on_call_users is parsed from API relationships
    for user in calendar.on_call_users:
        email = user.get("meta", {}).get("email", "Unknown")
        print(f"  On-call: {email}")

Get On-Call Events

Events are lazy-loaded when accessed.

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import OnCallCalendar

api = UptimeAPI("your-token")

for calendar in OnCallCalendar.get_all_instances(api):
    print(f"Calendar: {calendar.team_name}")

    # Events are fetched on first access
    for event in calendar.events:
        print(f"  {event.starts_at} - {event.ends_at}")
        print(f"    Users: {', '.join(event.users or [])}")
        print(f"    Override: {event.override}")

Create a Rotation

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import OnCallCalendar

api = UptimeAPI("your-token")

# Get the default calendar for a team
for calendar in OnCallCalendar.get_all_instances(api):
    if calendar.team_name == "Production" and calendar.default_calendar:
        # Create a weekly rotation
        result = calendar.create_rotation(
            users=[
                "alice@example.com",
                "bob@example.com",
                "charlie@example.com",
            ],
            rotation_length=1,
            rotation_period="week",
            start_rotations_at="2025-01-01T00:00:00Z",
            end_rotations_at="2025-12-31T23:59:59Z",
        )
        print(f"Created rotation: {result}")
        break

Working with Escalation Policies

Escalation policies use the v3 API endpoint.

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import EscalationPolicy, PolicyStep

api = UptimeAPI("your-token")

# Get all policies
for policy in EscalationPolicy.get_all_instances(api):
    print(f"Policy: {policy.name}")
    print(f"  Team: {policy.team_name}")
    print(f"  Repeat count: {policy.repeat_count}")
    print(f"  Steps: {len(policy.steps or [])}")

    for i, step in enumerate(policy.steps or []):
        print(f"    Step {i + 1}: {step['type']}")
        print(f"      Wait before: {step.get('wait_before', 0)}s")

Building Policy Steps

Use the PolicyStep helper class to construct escalation steps.

from betterstack.uptime.objects import PolicyStep

# Escalation step - notify current on-call immediately
step1 = PolicyStep(
    step_type="escalation",
    wait_before=0,
    urgency_id=123456,
    step_members=[{"type": "current_on_call"}],
)

# Escalation step - notify entire team after 10 minutes
step2 = PolicyStep(
    step_type="escalation",
    wait_before=600,
    urgency_id=123456,
    step_members=[{"type": "entire_team"}],
)

# Time branching step - route to different policy on weekends
weekend_step = PolicyStep(
    step_type="time_branching",
    wait_before=0,
    timezone="UTC",
    days=["sat", "sun"],
    time_from="00:00",
    time_to="23:59",
    policy_id=789,
)

# Convert to dict for API
steps = [step1.to_dict(), step2.to_dict()]