API Client

The API client classes handle all HTTP communication with the BetterStack Uptime API.

Quick Start

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import Monitor

# Initialize the client with your API token
api = UptimeAPI("your-bearer-token")

# Get all monitors
for monitor in Monitor.get_all_instances(api):
    print(f"{monitor.url}: {monitor.status}")

UptimeAPI

The main client class for interacting with the BetterStack Uptime API.

class betterstack.uptime.api.UptimeAPI(bearer_token: str, retries: int = 3, backoff_factor: float = 0.5, timeout: float = 30.0, max_workers: int = 5)

Bases: PaginatedAPI

BetterStack Uptime API client.

This is the main client class for interacting with the BetterStack Uptime API. It is pre-configured with the correct base URL and supports concurrent fetching of paginated results.

Example:

>>> api = UptimeAPI("your-bearer-token")
>>> monitors = list(Monitor.get_all_instances(api))

Attributes:

BETTERSTACK_API_URL: The base URL for the BetterStack Uptime API.

Initialize UptimeAPI with bearer token authentication.

Args:

bearer_token: Bearer token for API authentication. retries: Number of retries for failed requests. backoff_factor: Backoff factor for retry delays. timeout: Default timeout for requests in seconds. max_workers: Maximum number of threads for concurrent page fetching.

BETTERSTACK_API_URL = 'https://uptime.betterstack.com/api/v2/'

__init__(bearer_token: str, retries: int = 3, backoff_factor: float = 0.5, timeout: float = 30.0, max_workers: int = 5) → None

Initialize UptimeAPI with bearer token authentication.

Args:

bearer_token: Bearer token for API authentication. retries: Number of retries for failed requests. backoff_factor: Backoff factor for retry delays. timeout: Default timeout for requests in seconds. max_workers: Maximum number of threads for concurrent page fetching.

PaginatedAPI

Base class that handles automatic pagination of API responses.

class betterstack.uptime.api.PaginatedAPI(base_url: str, auth: BearerAuth, retries: int = 3, backoff_factor: float = 0.5, timeout: float = 30.0, max_workers: int = 5)

Bases: RESTAPI

REST API client that handles paginated responses.

This class extends RESTAPI to automatically follow pagination links and yield all results across multiple pages. Supports concurrent fetching of pages for improved performance.

Attributes:

max_workers: Maximum number of threads for concurrent page fetching.

Initialize PaginatedAPI with threading configuration.

Args:

base_url: The URL to be called, must end with a forward slash. auth: Authentication class to be used with requests. retries: Number of retries for failed requests. backoff_factor: Backoff factor for retry delays. timeout: Default timeout for requests in seconds. max_workers: Maximum number of threads for concurrent page fetching.

__init__(base_url: str, auth: BearerAuth, retries: int = 3, backoff_factor: float = 0.5, timeout: float = 30.0, max_workers: int = 5) → None

Initialize PaginatedAPI with threading configuration.

Args:

base_url: The URL to be called, must end with a forward slash. auth: Authentication class to be used with requests. retries: Number of retries for failed requests. backoff_factor: Backoff factor for retry delays. timeout: Default timeout for requests in seconds. max_workers: Maximum number of threads for concurrent page fetching.

get(url: str, body: dict[str, Any] | None = None, headers: dict[str, Any] | None = None, parameters: dict[str, Any] | None = None) → Generator[dict[str, Any], None, None]

Perform a GET request with automatic pagination and concurrent fetching.

This method fetches the first page to determine total pages, then fetches remaining pages concurrently using a thread pool. Results are yielded in page order.

Args:

url: URL path to access (relative to base_url). body: Request body (unused for GET). headers: Additional headers to send. parameters: URL query parameters.

Yields:

Individual items from the response data array.

RESTAPI

Low-level REST API client with retry logic and error handling.

class betterstack.uptime.api.RESTAPI(base_url: str, auth: BearerAuth, retries: int = 3, backoff_factor: float = 0.5, timeout: float = 30.0)

Bases: object

Low-level REST API client with session management and retry logic.

This class handles all HTTP communication with the BetterStack API, including authentication, request retries, and error handling.

Attributes:

base_url: The base URL for all API requests. session: The requests session used for all HTTP calls.

Initialize RESTAPI with session and retry configuration.

Args:

base_url: The URL to be called, must end with a forward slash. auth: Authentication class to be used with requests. retries: Number of retries for failed requests. backoff_factor: Backoff factor for retry delays. timeout: Default timeout for requests in seconds.

Raises:

ValueError: If base_url doesn’t end with a forward slash.

__init__(base_url: str, auth: BearerAuth, retries: int = 3, backoff_factor: float = 0.5, timeout: float = 30.0) → None

Initialize RESTAPI with session and retry configuration.

Args:

base_url: The URL to be called, must end with a forward slash. auth: Authentication class to be used with requests. retries: Number of retries for failed requests. backoff_factor: Backoff factor for retry delays. timeout: Default timeout for requests in seconds.

Raises:

ValueError: If base_url doesn’t end with a forward slash.

get(url: str, body: dict[str, Any] | None = None, headers: dict[str, Any] | None = None, parameters: dict[str, Any] | None = None) → dict[str, Any]

Perform a GET request.

Args:

url: URL path to access (relative to base_url). body: Request body (unused for GET, kept for interface consistency). headers: Additional headers to send. parameters: URL query parameters.

Returns:

Response JSON as a dictionary.

Raises:

APIError: If the request fails.

post(url: str, body: dict[str, Any] | None = None, headers: dict[str, Any] | None = None, parameters: dict[str, Any] | None = None) → Response

Perform a POST request.

Args:

url: URL path to access (relative to base_url). body: Request body as a dictionary (will be sent as JSON). headers: Additional headers to send. parameters: URL query parameters.

Returns:

Response object.

Raises:

APIError: If the request fails.

patch(url: str, body: dict[str, Any] | None = None, headers: dict[str, Any] | None = None, parameters: dict[str, Any] | None = None) → Response

Perform a PATCH request.

Args:

url: URL path to access (relative to base_url). body: Request body as a dictionary (will be sent as JSON). headers: Additional headers to send. parameters: URL query parameters.

Returns:

Response object.

Raises:

APIError: If the request fails.

delete(url: str, body: dict[str, Any] | None = None, headers: dict[str, Any] | None = None, parameters: dict[str, Any] | None = None) → Response

Perform a DELETE request.

Args:

url: URL path to access (relative to base_url). body: Request body (unused for DELETE). headers: Additional headers to send. parameters: URL query parameters.

Returns:

Response object.

Raises:

APIError: If the request fails.

Configuration Options

The UptimeAPI client accepts several configuration options:

Parameter	Default	Description
bearer_token	(required)	Your BetterStack API token
retries	3	Number of retry attempts for failed requests
backoff_factor	0.5	Multiplier for exponential backoff between retries
timeout	30.0	Request timeout in seconds

Example with custom configuration:

api = UptimeAPI(
    bearer_token="your-token",
    retries=5,
    backoff_factor=1.0,
    timeout=60.0,
)