API Objects Reference

This module contains all API resource objects that map to BetterStack Uptime API endpoints. Each object extends BaseAPIObject and provides:

Automatic attribute mapping from API responses
Change tracking for efficient updates (only modified fields are sent)
CRUD operations (create, read, update, delete)
Class methods for querying and filtering

Monitoring

Monitor

Bases: BaseAPIObject

Monitor resource from the BetterStack Uptime API.

A monitor represents a URL or service that is being monitored for uptime. Monitors can check HTTP endpoints, ping hosts, test TCP/UDP ports, and more.

Attributes:: url: The URL of your website or the host you want to ping. pronounceable_name: Human-readable name used in phone call alerts. monitor_type: Type of monitor (e.g., ‘status’, ‘keyword’, ‘ping’, ‘tcp’). monitor_group_id: ID of the monitor group this monitor belongs to. last_checked_at: When the monitor was last checked (ISO 8601 datetime). status: Current status (e.g., ‘up’, ‘down’, ‘paused’, ‘maintenance’). policy_id: The escalation policy ID for this monitor. expiration_policy_id: The expiration escalation policy ID. team_name: The team this monitor is in. required_keyword: Keyword that must be present (for keyword/udp monitors). verify_ssl: Whether to verify SSL certificate validity. check_frequency: How often to check, in seconds. call: Whether to call the on-call person on incidents. sms: Whether to send SMS on incidents. email: Whether to send email on incidents. push: Whether to send push notifications on incidents. critical_alert: Whether to send critical alert push notifications. team_wait: Seconds to wait before escalating to the team. http_method: HTTP method for requests (e.g., ‘GET’, ‘POST’). request_timeout: Request timeout in seconds (or ms for server monitors). recovery_period: Seconds before marking incident as resolved after recovery. request_headers: Array of custom HTTP headers with ‘name’ and ‘value’ properties. request_body: Request body for POST/PUT/PATCH, or domain for DNS monitors. paused_at: When the monitor was paused (ISO 8601 datetime), null if not paused. created_at: When the monitor was created (ISO 8601 datetime). updated_at: When the monitor was last updated (ISO 8601 datetime). ssl_expiration: Days before SSL expiration to alert. domain_expiration: Days before domain expiration to alert. regions: Array of regions to check from (e.g., ‘us’, ‘eu’, ‘as’, ‘au’). port: Port for TCP/UDP/SMTP/POP/IMAP monitors. confirmation_period: Seconds to wait after failure before starting incident. expected_status_codes: Array of acceptable HTTP status codes. maintenance_days: Array of maintenance days (e.g., ‘mon’, ‘tue’, ‘wed’). maintenance_from: Start of daily maintenance window (e.g., ‘01:00:00’). maintenance_to: End of daily maintenance window (e.g., ‘03:00:00’). maintenance_timezone: Timezone for maintenance window. playwright_script: JavaScript source code for Playwright monitors. environment_variables: Environment variables for Playwright scenarios. auth_username: Basic auth username. auth_password: Basic auth password. follow_redirects: Whether to follow HTTP redirects. remember_cookies: Whether to remember cookies between checks.

url: str | None = None

pronounceable_name: str | None = None

monitor_type: str | None = None

monitor_group_id: int | None = None

last_checked_at: str | None = None

status: str | None = None

policy_id: int | None = None

expiration_policy_id: int | None = None

team_name: str | None = None

required_keyword: str | None = None

verify_ssl: bool | None = None

check_frequency: int | None = None

call: bool | None = None

sms: bool | None = None

email: bool | None = None

push: bool | None = None

critical_alert: bool | None = None

team_wait: int | None = None

http_method: str | None = None

request_timeout: int | None = None

recovery_period: int | None = None

request_headers: list[dict[str, str]] | None = None

request_body: str | None = None

paused_at: str | None = None

created_at: str | None = None

updated_at: str | None = None

ssl_expiration: int | None = None

domain_expiration: int | None = None

regions: list[str] | None = None

port: str | None = None

confirmation_period: int | None = None

expected_status_codes: list[int] | None = None

maintenance_days: list[str] | None = None

maintenance_from: str | None = None

maintenance_to: str | None = None

maintenance_timezone: str | None = None

playwright_script: str | None = None

environment_variables: dict[str, Any] | None = None

auth_username: str | None = None

auth_password: str | None = None

follow_redirects: bool | None = None

remember_cookies: bool | None = None

property sla: MonitorSLA

Get or create the SLA object for this monitor.

Returns:: MonitorSLA object for this monitor.

property is_paused: bool

Check if the monitor is currently paused.

Returns:: True if the monitor is paused, False otherwise.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, url: str | None = None, pronounceable_name: str | None = None, monitor_type: str | None = None, monitor_group_id: int | None = None, last_checked_at: str | None = None, status: str | None = None, policy_id: int | None = None, expiration_policy_id: int | None = None, team_name: str | None = None, required_keyword: str | None = None, verify_ssl: bool | None = None, check_frequency: int | None = None, call: bool | None = None, sms: bool | None = None, email: bool | None = None, push: bool | None = None, critical_alert: bool | None = None, team_wait: int | None = None, http_method: str | None = None, request_timeout: int | None = None, recovery_period: int | None = None, request_headers: list[dict[str, str]] | None=None, request_body: str | None = None, paused_at: str | None = None, created_at: str | None = None, updated_at: str | None = None, ssl_expiration: int | None = None, domain_expiration: int | None = None, regions: list[str] | None = None, port: str | None = None, confirmation_period: int | None = None, expected_status_codes: list[int] | None = None, maintenance_days: list[str] | None = None, maintenance_from: str | None = None, maintenance_to: str | None = None, maintenance_timezone: str | None = None, playwright_script: str | None = None, environment_variables: dict[str, Any] | None=None, auth_username: str | None = None, auth_password: str | None = None, follow_redirects: bool | None = None, remember_cookies: bool | None = None, _sla: MonitorSLA | None = None) → None

Monitor SLA

class betterstack.uptime.objects.MonitorSLA(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, availability: float | None = None, downtime_duration: int | None = None, number_of_incidents: int | None = None, longest_incident: int | None = None, average_incident: int | None = None, _sla_start: str | None = None, _sla_end: str | None = None)[source]

Bases: BaseAPIObject

Monitor SLA (Service Level Agreement) data.

This object provides SLA statistics for a specific monitor over a given time period.

Attributes:: availability: Availability percentage (0-100). downtime_duration: Total downtime in seconds. number_of_incidents: Number of incidents in the period. longest_incident: Duration of longest incident in seconds. average_incident: Average incident duration in seconds.

availability: float | None = None

downtime_duration: int | None = None

number_of_incidents: int | None = None

longest_incident: int | None = None

average_incident: int | None = None

generate_url() → str[source]

Create the URL for this SLA endpoint.

Returns:: Full SLA URL path.

classmethod generate_global_url() → str[source]

SLA objects don’t have a global URL.

Raises:: ValueError: Always, as SLA has no collection endpoint.

property timeframe: tuple[str | None, str | None]

Get the current SLA timeframe.

Returns:: Tuple of (start_date, end_date).

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, availability: float | None = None, downtime_duration: int | None = None, number_of_incidents: int | None = None, longest_incident: int | None = None, average_incident: int | None = None, _sla_start: str | None = None, _sla_end: str | None = None) → None

fetch_sla(from_date: str, to_date: str) → None[source]

Fetch SLA data for a specific time period.

Args:: from_date: Start date in ISO 8601 format. to_date: End date in ISO 8601 format.

Monitor Groups

class betterstack.uptime.objects.MonitorGroup(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, sort_index: int | None = None, created_at: str | None = None, updated_at: str | None = None, paused: bool | None = None, team_name: str | None = None, _monitors: list[Monitor] | None = None)[source]

Bases: BaseAPIObject

Monitor Group resource from the BetterStack Uptime API.

A monitor group is a collection of monitors that can be managed together. Groups help organize monitors logically and can be paused/resumed as a unit.

Attributes:: name: The name of the monitor group. sort_index: Sort order for the group in the dashboard. created_at: When the group was created (ISO 8601 format). updated_at: When the group was last updated (ISO 8601 format). paused: Whether all monitors in the group are paused. team_name: The team that owns this monitor group (for filtering).

name: str | None = None

sort_index: int | None = None

created_at: str | None = None

updated_at: str | None = None

paused: bool | None = None

team_name: str | None = None

property monitors: list[Monitor]

Get monitors in this group, fetching if necessary.

Returns:: List of Monitor objects in this group.

fetch_monitors() → None[source]: Fetch all monitors belonging to this group.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, sort_index: int | None = None, created_at: str | None = None, updated_at: str | None = None, paused: bool | None = None, team_name: str | None = None, _monitors: list[Monitor] | None = None) → None

Heartbeats

Heartbeat

Bases: BaseAPIObject

Heartbeat resource from the BetterStack Uptime API.

A heartbeat monitor expects regular “heartbeat” pings from your application. If a ping is not received within the expected period, an incident is triggered.

Attributes:: name: The name of the heartbeat. url: The unique URL to ping for this heartbeat. period: Expected time between heartbeats in seconds. grace: Grace period in seconds before triggering an incident. call: Whether to make phone calls on incidents. sms: Whether to send SMS on incidents. email: Whether to send emails on incidents. push: Whether to send push notifications on incidents. critical_alert: Whether to send as a critical/high-urgency alert. team_wait: Seconds to wait before escalating to the team. heartbeat_group_id: ID of the heartbeat group this belongs to. team_name: The team that owns this heartbeat (for filtering). sort_index: Sort order for the heartbeat in the dashboard. paused_at: When the heartbeat was paused (ISO 8601), if paused. created_at: When the heartbeat was created (ISO 8601 format). updated_at: When the heartbeat was last updated (ISO 8601 format). status: Current status of the heartbeat (e.g., “up”, “down”, “paused”). maintenance_from: Start time of the maintenance window (HH:MM:SS format). maintenance_to: End time of the maintenance window (HH:MM:SS format). maintenance_timezone: Timezone for the maintenance window. maintenance_days: List of days for maintenance (e.g., [“mon”, “tue”]). policy_id: ID of the escalation policy for this heartbeat.

name: str | None = None

url: str | None = None

period: int | None = None

grace: int | None = None

call: bool | None = None

sms: bool | None = None

email: bool | None = None

push: bool | None = None

critical_alert: bool | None = None

team_wait: int | None = None

heartbeat_group_id: int | None = None

team_name: str | None = None

sort_index: int | None = None

paused_at: str | None = None

created_at: str | None = None

updated_at: str | None = None

status: str | None = None

maintenance_from: str | None = None

maintenance_to: str | None = None

maintenance_timezone: str | None = None

maintenance_days: list[str] | None = None

policy_id: int | None = None

property is_paused: bool

Check if the heartbeat is currently paused.

Returns:: True if the heartbeat has a paused_at timestamp.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, url: str | None = None, period: int | None = None, grace: int | None = None, call: bool | None = None, sms: bool | None = None, email: bool | None = None, push: bool | None = None, critical_alert: bool | None = None, team_wait: int | None = None, heartbeat_group_id: int | None = None, team_name: str | None = None, sort_index: int | None = None, paused_at: str | None = None, created_at: str | None = None, updated_at: str | None = None, status: str | None = None, maintenance_from: str | None = None, maintenance_to: str | None = None, maintenance_timezone: str | None = None, maintenance_days: list[str] | None = None, policy_id: int | None = None) → None

Heartbeat Groups

class betterstack.uptime.objects.HeartbeatGroup(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, sort_index: int | None = None, created_at: str | None = None, updated_at: str | None = None, paused: bool | None = None, team_name: str | None = None, _heartbeats: list[Heartbeat] | None = None)[source]

Bases: BaseAPIObject

Heartbeat Group resource from the BetterStack Uptime API.

A heartbeat group is a collection of heartbeat monitors that can be managed together. Groups help organize heartbeats logically and can be paused/resumed as a unit.

Attributes:: name: The name of the heartbeat group. sort_index: Sort order for the group in the dashboard. created_at: When the group was created (ISO 8601 format). updated_at: When the group was last updated (ISO 8601 format). paused: Whether all heartbeats in the group are paused. team_name: The team that owns this heartbeat group (for filtering).

name: str | None = None

sort_index: int | None = None

created_at: str | None = None

updated_at: str | None = None

paused: bool | None = None

team_name: str | None = None

property heartbeats: list[Heartbeat]

Get heartbeats in this group, fetching if necessary.

Returns:: List of Heartbeat objects in this group.

fetch_heartbeats() → None[source]: Fetch all heartbeats belonging to this group.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, sort_index: int | None = None, created_at: str | None = None, updated_at: str | None = None, paused: bool | None = None, team_name: str | None = None, _heartbeats: list[Heartbeat] | None = None) → None

Incidents

Bases: BaseAPIObject

Incident resource from the BetterStack Uptime API (v3).

An incident represents a period of downtime or issues detected by a monitor or heartbeat. Incidents are automatically created when a monitor or heartbeat fails and can be acknowledged and resolved manually or automatically.

Note:: This resource uses the v3 API endpoint (/api/v3/incidents).
Attributes:: name: The name/title of the incident. url: The URL that triggered the incident (for URL monitors). http_method: The HTTP method used when the incident was detected. cause: The cause of the incident (e.g., “Keyword not found”). incident_group_id: ID of the incident group this incident belongs to. started_at: When the incident started (ISO 8601 format). acknowledged_at: When the incident was acknowledged (ISO 8601 format). acknowledged_by: Name of who acknowledged the incident. resolved_at: When the incident was resolved (ISO 8601 format). resolved_by: Name of who resolved the incident. status: Current status of the incident (e.g., “Started”, “Resolved”). team_name: The team that owns this incident (for filtering). response_content: The response body content when the incident occurred. response_url: The final URL after any redirects. response_options: Additional response information/options. regions: List of regions where the incident was detected. screenshot_url: URL to a screenshot taken during the incident. origin_url: The original URL before any redirects. escalation_policy_id: ID of the escalation policy that was triggered. ssl_certificate_expires_at: When the SSL certificate expires. domain_expires_at: When the domain expires. call: Whether phone calls were made for this incident. sms: Whether SMS was sent for this incident. email: Whether email was sent for this incident. push: Whether push notifications were sent for this incident. critical_alert: Whether critical/high-urgency alerts were sent. metadata: Custom metadata dictionary attached to this incident. monitor_id: ID of the monitor that triggered this incident. heartbeat_id: ID of the heartbeat that triggered this incident.

name: str | None = None

url: str | None = None

http_method: str | None = None

cause: str | None = None

incident_group_id: int | None = None

started_at: str | None = None

acknowledged_at: str | None = None

acknowledged_by: str | None = None

resolved_at: str | None = None

resolved_by: str | None = None

status: str | None = None

team_name: str | None = None

response_content: str | None = None

response_url: str | None = None

response_options: dict[str, Any] | None = None

regions: list[str] | None = None

screenshot_url: str | None = None

origin_url: str | None = None

escalation_policy_id: int | None = None

ssl_certificate_expires_at: str | None = None

domain_expires_at: str | None = None

call: bool | None = None

sms: bool | None = None

email: bool | None = None

push: bool | None = None

critical_alert: bool | None = None

metadata: dict[str, Any] | None = None

monitor_id: int | None = None

heartbeat_id: int | None = None

property is_resolved: bool

Check if the incident has been resolved.

Returns:: True if the incident has a resolved_at timestamp or status is “Resolved”.

property is_acknowledged: bool

Check if the incident has been acknowledged.

Returns:: True if the incident has an acknowledged_at timestamp or status is “Acknowledged”.

acknowledge(acknowledged_by: str | None = None) → None[source]

Acknowledge this incident.

Acknowledging an incident indicates that someone is aware of the issue and is working on it. This stops further escalations.

Args:

acknowledged_by: Optional name of who is acknowledging: the incident.

resolve(resolved_by: str | None = None) → None[source]

Resolve this incident.

Resolving an incident marks it as fixed. This stops all notifications and escalations for this incident.

Args:: resolved_by: Optional name of who is resolving the incident.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, url: str | None = None, http_method: str | None = None, cause: str | None = None, incident_group_id: int | None = None, started_at: str | None = None, acknowledged_at: str | None = None, acknowledged_by: str | None = None, resolved_at: str | None = None, resolved_by: str | None = None, status: str | None = None, team_name: str | None = None, response_content: str | None = None, response_url: str | None = None, response_options: dict[str, Any] | None=None, regions: list[str] | None = None, screenshot_url: str | None = None, origin_url: str | None = None, escalation_policy_id: int | None = None, ssl_certificate_expires_at: str | None = None, domain_expires_at: str | None = None, call: bool | None = None, sms: bool | None = None, email: bool | None = None, push: bool | None = None, critical_alert: bool | None = None, metadata: dict[str, Any] | None=None, monitor_id: int | None = None, heartbeat_id: int | None = None) → None

Note

Incidents use the BetterStack v3 API endpoint (/api/v3/incidents) which provides additional filtering capabilities and attributes compared to the v2 API.

Status Pages

StatusPage

Bases: BaseAPIObject

StatusPage resource from the BetterStack Uptime API.

A status page displays the current operational status of your services and provides a public-facing view for your users.

Attributes:: company_name: The name of the company. company_url: The URL of the company website. contact_url: URL for emergency contact. logo_url: URL of the company logo. timezone: Timezone for the status page. subdomain: Subdomain for the status page (e.g., ‘my-company’). custom_domain: Custom domain for the status page. custom_css: Custom CSS for the status page. custom_javascript: Custom JavaScript for the status page. google_analytics_id: Google Analytics ID for tracking. min_incident_length: Minimum incident length in seconds to display. announcement: Announcement text to display. announcement_embed_visible: Whether the announcement embed is visible. announcement_embed_css: Custom CSS for the announcement embed. announcement_embed_link: Link for the announcement embed. automatic_reports: Whether automatic reports are enabled. status_page_group_id: ID of the status page group. subscribable: Whether users can subscribe to updates. hide_from_search_engines: Whether to hide from search engines. password_enabled: Whether password protection is enabled. ip_allowlist: List of allowed IP addresses or CIDR ranges. history: Number of days to display on the status page. aggregate_state: Current aggregate operational state. design: Design version (‘v1’ or ‘v2’). navigation_links: Navigation links for the status page. theme: Theme of the status page (‘light’, ‘dark’, ‘system’). layout: Layout of the status page (‘vertical’, ‘horizontal’). created_at: When the status page was created. updated_at: When the status page was last updated.

company_name: str | None = None

company_url: str | None = None

contact_url: str | None = None

logo_url: str | None = None

timezone: str | None = None

subdomain: str | None = None

custom_domain: str | None = None

custom_css: str | None = None

custom_javascript: str | None = None

google_analytics_id: str | None = None

min_incident_length: int | None = None

announcement: str | None = None

announcement_embed_visible: bool | None = None

announcement_embed_css: str | None = None

announcement_embed_link: str | None = None

automatic_reports: bool | None = None

status_page_group_id: int | None = None

subscribable: bool | None = None

hide_from_search_engines: bool | None = None

password_enabled: bool | None = None

ip_allowlist: list[str] | None = None

history: int | None = None

aggregate_state: str | None = None

design: str | None = None

navigation_links: list[dict[str, str]] | None = None

theme: str | None = None

layout: str | None = None

created_at: str | None = None

updated_at: str | None = None

property sections: list[StatusPageSection]

Get the sections for this status page (lazy-loaded).

Returns:: List of StatusPageSection objects.

property resources: list[StatusPageResource]

Get the resources for this status page (lazy-loaded).

Returns:: List of StatusPageResource objects.

fetch_sections() → list[StatusPageSection][source]

Fetch all sections for this status page from the API.

Returns:: List of StatusPageSection objects.

fetch_resources() → list[StatusPageResource][source]

Fetch all resources for this status page from the API.

Returns:: List of StatusPageResource objects.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, company_name: str | None = None, company_url: str | None = None, contact_url: str | None = None, logo_url: str | None = None, timezone: str | None = None, subdomain: str | None = None, custom_domain: str | None = None, custom_css: str | None = None, custom_javascript: str | None = None, google_analytics_id: str | None = None, min_incident_length: int | None = None, announcement: str | None = None, announcement_embed_visible: bool | None = None, announcement_embed_css: str | None = None, announcement_embed_link: str | None = None, automatic_reports: bool | None = None, status_page_group_id: int | None = None, subscribable: bool | None = None, hide_from_search_engines: bool | None = None, password_enabled: bool | None = None, ip_allowlist: list[str] | None = None, history: int | None = None, aggregate_state: str | None = None, design: str | None = None, navigation_links: list[dict[str, str]] | None=None, theme: str | None = None, layout: str | None = None, created_at: str | None = None, updated_at: str | None = None, _sections: list[StatusPageSection] | None = None, _resources: list[StatusPageResource] | None = None) → None

StatusPageSection

class betterstack.uptime.objects.StatusPageSection(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, position: int | None = None, created_at: str | None = None, updated_at: str | None = None, _status_page_id: str | None = None)[source]

Bases: BaseAPIObject

StatusPageSection resource from the BetterStack Uptime API.

A section is a grouping of resources on a status page.

Attributes:: name: The name of the section. position: The position of the section on the status page. created_at: When the section was created. updated_at: When the section was last updated.

name: str | None = None

position: int | None = None

created_at: str | None = None

updated_at: str | None = None

generate_url() → str[source]

Create the URL for this section endpoint.

Returns:: Full section URL path.
Raises:: ValueError: If status_page_id is not set.

classmethod generate_global_url() → str[source]

Sections don’t have a global URL without a status page ID.

Raises:: ValueError: Always, as sections require a status page ID.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, position: int | None = None, created_at: str | None = None, updated_at: str | None = None, _status_page_id: str | None = None) → None

StatusPageResource

class betterstack.uptime.objects.StatusPageResource(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, status_page_section_id: int | None = None, resource_id: int | None = None, resource_type: str | None = None, history: bool | None = None, widget_type: str | None = None, public_name: str | None = None, explanation: str | None = None, position: int | None = None, fixed_position: bool | None = None, availability: float | None = None, status: str | None = None, status_history: list[dict[str, Any]] | None=None, _status_page_id: str | None = None)[source]

Bases: BaseAPIObject

StatusPageResource resource from the BetterStack Uptime API.

A resource represents a monitor, heartbeat, or other item displayed on a status page.

Attributes:: status_page_section_id: ID of the section containing this resource. resource_id: ID of the underlying resource (monitor, heartbeat, etc.). resource_type: Type of the resource (‘Monitor’, ‘Heartbeat’, etc.). history: Whether to show history for this resource. widget_type: Widget type (‘plain’, ‘history’, ‘response_times’, ‘chart_only’). public_name: Public name displayed on the status page. explanation: Help text for the resource. position: Position of the resource on the status page. fixed_position: Whether position reorders are prevented. availability: Availability percentage of the resource. status: Current operational status. status_history: Historical status data.

status_page_section_id: int | None = None

resource_id: int | None = None

resource_type: str | None = None

history: bool | None = None

widget_type: str | None = None

public_name: str | None = None

explanation: str | None = None

position: int | None = None

fixed_position: bool | None = None

availability: float | None = None

status: str | None = None

status_history: list[dict[str, Any]] | None = None

generate_url() → str[source]

Create the URL for this resource endpoint.

Returns:: Full resource URL path.
Raises:: ValueError: If status_page_id is not set.

classmethod generate_global_url() → str[source]

Resources don’t have a global URL without a status page ID.

Raises:: ValueError: Always, as resources require a status page ID.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, status_page_section_id: int | None = None, resource_id: int | None = None, resource_type: str | None = None, history: bool | None = None, widget_type: str | None = None, public_name: str | None = None, explanation: str | None = None, position: int | None = None, fixed_position: bool | None = None, availability: float | None = None, status: str | None = None, status_history: list[dict[str, Any]] | None=None, _status_page_id: str | None = None) → None

StatusPageGroup

class betterstack.uptime.objects.StatusPageGroup(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, sort_index: int | None = None, created_at: str | None = None, updated_at: str | None = None)[source]

Bases: BaseAPIObject

StatusPageGroup resource from the BetterStack Uptime API.

A status page group is used to organize multiple status pages.

Attributes:: name: The name of the group. sort_index: Sorting index for the group. created_at: When the group was created. updated_at: When the group was last updated.

name: str | None = None

sort_index: int | None = None

created_at: str | None = None

updated_at: str | None = None

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, sort_index: int | None = None, created_at: str | None = None, updated_at: str | None = None) → None

On-Call Scheduling

OnCallCalendar

class betterstack.uptime.objects.OnCallCalendar(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, default_calendar: bool | None = None, team_name: str | None = None, _on_call_users: list[dict[str, Any]] | None=None, _events: list[OnCallEvent] | None = None)[source]

Bases: BaseAPIObject

OnCallCalendar resource from the BetterStack Uptime API.

An on-call calendar (schedule) defines who is on-call and when. It manages on-call rotations and events for incident response.

Attributes:: name: The name of the schedule. default_calendar: Whether this is the default calendar for the team. team_name: Name of the team associated with the schedule.

name: str | None = None

default_calendar: bool | None = None

team_name: str | None = None

property on_call_users: list[dict[str, Any]]

Get the current on-call users for this calendar.

Returns:: List of user data dictionaries.

property events: list[OnCallEvent]

Get the events for this on-call calendar (lazy-loaded).

Returns:: List of OnCallEvent objects.

fetch_events() → list[OnCallEvent][source]

Fetch all events for this on-call calendar from the API.

Returns:: List of OnCallEvent objects.

create_rotation(users: list[str], rotation_length: int, rotation_period: str, start_rotations_at: str, end_rotations_at: str) → dict[str, Any][source]

Create an on-call rotation for this calendar.

Args:: users: List of email addresses of users to include. rotation_length: Length of the rotation period. rotation_period: Period type (‘hour’, ‘day’, ‘week’). start_rotations_at: Start time in ISO 8601 format. end_rotations_at: End time in ISO 8601 format.
Returns:: API response data for the created rotation.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, default_calendar: bool | None = None, team_name: str | None = None, _on_call_users: list[dict[str, Any]] | None=None, _events: list[OnCallEvent] | None = None) → None

OnCallEvent

class betterstack.uptime.objects.OnCallEvent(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, starts_at: str | None = None, ends_at: str | None = None, users: list[str] | None = None, override: bool | None = None, _calendar_id: str | None = None)[source]

Bases: BaseAPIObject

OnCallEvent resource from the BetterStack Uptime API.

An on-call event represents a time period when specific users are on-call.

Attributes:: starts_at: Start time of the event in ISO 8601 format. ends_at: End time of the event in ISO 8601 format. users: List of email addresses of users on-call during this event. override: Whether this is an override event.

starts_at: str | None = None

ends_at: str | None = None

users: list[str] | None = None

override: bool | None = None

generate_url() → str[source]

Create the URL for this event endpoint.

Returns:: Full event URL path.
Raises:: ValueError: If calendar_id is not set.

classmethod generate_global_url() → str[source]

Events don’t have a global URL without a calendar ID.

Raises:: ValueError: Always, as events require a calendar ID.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, starts_at: str | None = None, ends_at: str | None = None, users: list[str] | None = None, override: bool | None = None, _calendar_id: str | None = None) → None

Escalation Policies

EscalationPolicy

class betterstack.uptime.objects.EscalationPolicy(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, repeat_count: int | None = None, repeat_delay: int | None = None, incident_token: str | None = None, policy_group_id: int | None = None, team_name: str | None = None, steps: list[dict[str, Any]] | None=None)[source]

Bases: BaseAPIObject

EscalationPolicy resource from the BetterStack Uptime API.

An escalation policy defines the sequence of notifications sent when an incident occurs. It specifies who to notify and in what order.

Note: This resource uses the v3 API endpoint.

Attributes:: name: The name of the policy. repeat_count: How many times to repeat the escalation steps. repeat_delay: Seconds to wait before each repetition. incident_token: Token for manually reporting incidents. policy_group_id: ID of the policy group. team_name: Name of the team that owns the policy. steps: List of escalation steps.

name: str | None = None

repeat_count: int | None = None

repeat_delay: int | None = None

incident_token: str | None = None

policy_group_id: int | None = None

team_name: str | None = None

steps: list[dict[str, Any]] | None = None

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>, name: str | None = None, repeat_count: int | None = None, repeat_delay: int | None = None, incident_token: str | None = None, policy_group_id: int | None = None, team_name: str | None = None, steps: list[dict[str, Any]] | None=None) → None

Note

Escalation policies use the BetterStack v3 API endpoint (/api/v3/policies).

PolicyStep

class betterstack.uptime.objects.PolicyStep(step_type: str = 'escalation', wait_before: int = 0, urgency_id: int | None = None, step_members: list[dict[str, str]] | None = None, timezone: str | None = None, days: list[str] | None = None, time_from: str | None = None, time_to: str | None = None, policy_id: int | None = None, policy_metadata_key: str | None = None)[source]

Bases: object

Represents a single step in an escalation policy.

This is a helper class for constructing escalation policy steps. It is not a full API object but can be used when creating policies.

Attributes:: step_type: Type of step (‘escalation’ or ‘time_branching’). wait_before: Seconds to wait before executing this step. urgency_id: ID of the urgency level for this step. step_members: List of members to notify. timezone: Timezone for time branching steps. days: Days of the week for time branching. time_from: Start time for time branching. time_to: End time for time branching. policy_id: ID of the policy to branch to. policy_metadata_key: Metadata key for the branched policy.

step_type: str = 'escalation'

wait_before: int = 0

urgency_id: int | None = None

step_members: list[dict[str, str]] | None = None

timezone: str | None = None

days: list[str] | None = None

time_from: str | None = None

time_to: str | None = None

policy_id: int | None = None

policy_metadata_key: str | None = None

to_dict() → dict[str, Any][source]

Convert step to dictionary for API requests.

Returns:: Dictionary representation of the step.

__init__(step_type: str = 'escalation', wait_before: int = 0, urgency_id: int | None = None, step_members: list[dict[str, str]] | None = None, timezone: str | None = None, days: list[str] | None = None, time_from: str | None = None, time_to: str | None = None, policy_id: int | None = None, policy_metadata_key: str | None = None) → None

Note

PolicyStep is a helper dataclass for constructing policy steps. It is not an API object and cannot be used for direct API operations.