Python Betterstack-Uptime

betterstack-uptime is a library written in python that can assist in dealing with the Betterstack Uptime API. This is done by converting API endpoints into python objects, and translating the attributes from the API into variables.

Current endpoints implemented

Monitoring

• Monitors
• Monitor SLA
• Monitor Groups
• Heartbeats
• Heartbeat Groups
• Incidents

Status Pages

• Status Pages
• Status Page Sections
• Status Page Resources
• Status Page Groups

On-call & Escalations

• On-Call Calendars
• On-Call Events
• Escalation Policies (v3 API)

If you need another endpoint, feel free to extend the BaseAPIObject class and implement it!

betterstack-uptime is free and open source software, you are free to use it, share it, modify it and share the modifications with the world.

Getting Started

Requirements

You will need the following software:

• python >= 3.10

Python 3.10+ is required for type hint syntax support.

Installing

Run the following command to install the package

pip install betterstack-uptime

Usage

Just some quick boilerplate code to get you started

Get all instances

frombetterstack.uptimeimportUptimeAPIfrombetterstack.uptime.objectsimportMonitorapi=UptimeAPI("yourtokenhere")
monitors=Monitor.get_all_instances(api=api)
formonitorinmonitors:
print(monitor.url)

Working with Status Pages

frombetterstack.uptimeimportUptimeAPIfrombetterstack.uptime.objectsimportStatusPageapi=UptimeAPI("yourtokenhere")
# Get all status pagesforstatus_pageinStatusPage.get_all_instances(api):
print(f"{status_page.company_name}: {status_page.aggregate_state}")
# Lazy-loaded sections and resourcesforsectioninstatus_page.sections:
print(f" Section: {section.name}")
forresourceinstatus_page.resources:
print(f" Resource: {resource.public_name} - {resource.status}")

Working with On-Call Calendars

frombetterstack.uptimeimportUptimeAPIfrombetterstack.uptime.objectsimportOnCallCalendarapi=UptimeAPI("yourtokenhere")
# Get all on-call calendarsforcalendarinOnCallCalendar.get_all_instances(api):
print(f"{calendar.team_name}: {calendar.name}")
# Get current on-call usersforuserincalendar.on_call_users:
print(f" On-call: {user.get('meta', {}).get('email')}")
# Create a rotationcalendar.create_rotation(
users=["alice@example.com", "bob@example.com"],
rotation_length=1,
rotation_period="week",
start_rotations_at="2025-01-01T00:00:00Z",
end_rotations_at="2025-12-31T23:59:59Z",
)

Working with Escalation Policies

frombetterstack.uptimeimportUptimeAPIfrombetterstack.uptime.objectsimportEscalationPolicy, PolicyStepapi=UptimeAPI("yourtokenhere")
# Get all escalation policies (uses v3 API)forpolicyinEscalationPolicy.get_all_instances(api):
print(f"{policy.name}: {len(policy.steps)} steps")
# Create a new policy with helper classsteps= [
PolicyStep(
step_type="escalation",
wait_before=0,
urgency_id=123456,
step_members=[{"type": "current_on_call"}],
).to_dict(),
PolicyStep(
step_type="escalation",
wait_before=600, # 10 minutesurgency_id=123456,
step_members=[{"type": "entire_team"}],
).to_dict(),
]

Documentation

Full documentation is available at https://iwink.github.io/python-betterstack-uptime/

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to me.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Wouter Mellema - Initial work - wmellema

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details