Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/openstatusHQ/openstatus. 🫖 Status page with uptime monitoring & API monitoring as code 🫖 openstatus.dev
bun drizzle-orm monitoring monitoring-as-code nextjs observability on-call open-source shadcn-ui status-page statuspage synthetic-monitoring tinybird turso uptime uptime-checker uptime-monitor
Something went wrong. Try again.
MDX
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212---category: SDKtitle: Python SDKdescription: "Interact with openstatus programmatically from your Python applications"---
The openstatus Python SDK lets you manage monitors, status pages, status reports, maintenance windows, and notifications from Python code, scripts, and automations. It ships both synchronous and asynchronous clients with identical, fully typed method signatures.
The SDK is open source and developed in its own repository, [openstatusHQ/sdk-python](https://github.com/openstatusHQ/sdk-python), and published on [PyPI](https://pypi.org/project/openstatus/).
## Features
- **HTTP, TCP, and DNS monitoring** — monitor websites, APIs, database connections, and DNS records from 28 locations worldwide. (ICMP and gRPC monitors exist in the API but are not yet exposed by this SDK.)- **Status pages** — create and manage public status pages with monitor-based or static components, grouping, and subscribers.- **Status reports and maintenance** — manage incident reports with update timelines and schedule planned maintenance windows.- **Notifications** — configure all 13 channels: Slack, Discord, Microsoft Teams, Email, SMS, WhatsApp, Telegram, PagerDuty, Opsgenie, Google Chat, Grafana OnCall, ntfy, and generic webhooks.- **Sync and async** — `OpenstatusClient` and `AsyncOpenstatusClient` share the same API surface.- **Type-safe** — typed request/response messages generated from the openstatus protobuf schemas.
## Get Your API Key
Before using the SDK, you need an API key:
1. Log in to the [openstatus dashboard](https://app.openstatus.dev/login)2. Go to **Settings** > **General** and find the **API Keys** card3. Click **Create** and copy the key
<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>
## Installation
Requires Python 3.10 or later.
```bashpip install openstatus# oruv add openstatus```
## Authentication
Authentication uses the `OPENSTATUS_API_KEY` environment variable by default:
```bashexport OPENSTATUS_API_KEY="your-key-here"```
Alternatively, pass credentials programmatically:
```pythonfrom openstatus import ClientOptions, OpenstatusClient
client = OpenstatusClient(ClientOptions(api_key="your-key"))```
## Quick Start
The SDK offers both synchronous and asynchronous clients with identical method signatures.
**Sync:**
```pythonfrom openstatus import OpenstatusClientfrom openstatus._gen.openstatus.health.v1.health_pb2 import CheckRequest
with OpenstatusClient() as client: health = client.health.v1.HealthService.check(CheckRequest()) print(health.status)```
**Async:**
```pythonimport asynciofrom openstatus import AsyncOpenstatusClientfrom openstatus._gen.openstatus.health.v1.health_pb2 import CheckRequest
async def main(): async with AsyncOpenstatusClient() as client: health = await client.health.v1.HealthService.check(CheckRequest()) print(health.status)
asyncio.run(main())```
## Services
The SDK covers six primary services with typed request/response objects.
| Service | Accessor | Purpose ||---------|----------|---------|| Monitor | `client.monitor.v1.MonitorService` | Manage HTTP, TCP, and DNS monitors; trigger checks; read status and summaries. || Health | `client.health.v1.HealthService` | Liveness check for the API. No authentication required. || Status Report | `client.status_report.v1.StatusReportService` | Manage incident reports and their update timelines. || Status Page | `client.status_page.v1.StatusPageService` | Manage status pages, components, component groups, and subscribers. || Maintenance | `client.maintenance.v1.MaintenanceService` | Schedule and manage planned maintenance windows. || Notification | `client.notification.v1.NotificationService` | Configure notification channels and check usage limits. |
### Monitors
```pythonfrom openstatus._gen.openstatus.monitor.v1.service_pb2 import ( ListMonitorsRequest, GetMonitorRequest, TriggerMonitorRequest,)
client.monitor.v1.MonitorService.list_monitors(ListMonitorsRequest())client.monitor.v1.MonitorService.get_monitor(GetMonitorRequest(id="abc"))client.monitor.v1.MonitorService.trigger_monitor(TriggerMonitorRequest(id="abc"))```
### Status pages, reports, and maintenance
```pythonfrom openstatus._gen.openstatus.status_report.v1.service_pb2 import ListStatusReportsRequestfrom openstatus._gen.openstatus.status_page.v1.service_pb2 import ListStatusPagesRequestfrom openstatus._gen.openstatus.maintenance.v1.service_pb2 import ListMaintenancesRequest
client.status_report.v1.StatusReportService.list_status_reports(ListStatusReportsRequest())client.status_page.v1.StatusPageService.list_status_pages(ListStatusPagesRequest())client.maintenance.v1.MaintenanceService.list_maintenances(ListMaintenancesRequest())```
### Notifications
```pythonfrom openstatus._gen.openstatus.notification.v1.service_pb2 import ListNotificationsRequest
client.notification.v1.NotificationService.list_notifications(ListNotificationsRequest())```
## Advanced Configuration
Customize HTTP behavior by passing your own `httpx` client:
```pythonimport httpxfrom openstatus import ClientOptions, OpenstatusClient
http = httpx.Client( timeout=httpx.Timeout(connect=2.0, read=10.0, write=10.0, pool=10.0), transport=httpx.HTTPTransport(retries=3),)client = OpenstatusClient(ClientOptions(http_client=http))```
## Error Handling
The SDK provides a typed exception hierarchy for different failure scenarios:
```pythonfrom openstatus import ( AuthenticationError, NotFoundError, OpenstatusError, OpenstatusClient,)
try: result = client.monitor.v1.MonitorService.get_monitor(request)except NotFoundError as err: print(f"Not found: {err.http_status}")except AuthenticationError: print("Invalid credentials")except OpenstatusError as err: print(f"Error: {err.connect_code}")```
## Framework Integration
### FastAPI
```pythonfrom fastapi import Depends, FastAPIfrom openstatus import OpenstatusClient
app = FastAPI()_client = OpenstatusClient()
def get_client() -> OpenstatusClient: return _client
@app.on_event("shutdown")def shutdown(): _client.close()```
### Django
```pythonfrom django.conf import settingsfrom openstatus import ClientOptions, OpenstatusClient
_singleton = None
def client() -> OpenstatusClient: global _singleton if _singleton is None: _singleton = OpenstatusClient( ClientOptions(api_key=settings.OPENSTATUS_API_KEY) ) return _singleton```
## Resources
- [openstatusHQ/sdk-python on GitHub](https://github.com/openstatusHQ/sdk-python)- [openstatus on PyPI](https://pypi.org/project/openstatus/)- [API Reference](https://api.openstatus.dev/openapi)