UptimeClient¶

Client for the Kibana Uptime API.

The Uptime app in Kibana uses Heartbeat data to monitor the availability of services. The Uptime settings API lets you read and update the app-wide settings: the Heartbeat index pattern used to query monitoring data, TLS certificate alerting thresholds, and default alert connectors and email recipients.

Uptime settings are space-scoped: each Kibana space keeps its own settings document. Every method accepts an optional space_id to target a specific space.

Reading the settings requires read privileges for the uptime feature in the Observability section of the Kibana feature privileges; updating them requires all privileges.

class kibana._sync.client.uptime.UptimeClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Uptime API.

Uptime settings are space-scoped: each Kibana space keeps its own settings document. Every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Reading the settings requires read privileges for the uptime feature in the Observability section of the Kibana feature privileges; updating them requires all privileges.

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Read the current settings
>>> settings = client.uptime.get_settings()
>>> print(settings.body["heartbeatIndices"])
heartbeat-*
>>>
>>> # Partially update a single setting (other keys are preserved)
>>> updated = client.uptime.update_settings(cert_age_threshold=365)
>>> print(updated.body["certAgeThreshold"])
365

Reading Settings

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

settings = client.uptime.get_settings()
print(settings.body["heartbeatIndices"])
print(settings.body["certAgeThreshold"])
print(settings.body["certExpirationThreshold"])

Updating Settings

Updates are partial: only the settings you pass are changed, other keys are preserved:

# Update a single setting
updated = client.uptime.update_settings(cert_age_threshold=365)
print(updated.body["certAgeThreshold"])

# Update several settings at once
updated = client.uptime.update_settings(
    heartbeat_indices="heartbeat-*",
    cert_expiration_threshold=30,
    default_connectors=["my-connector-id"],
)

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the UptimeClient.

Parameters:

client (Kibana) – The parent Kibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> uptime_client = UptimeClient(kibana_client)

get_settings(*, space_id=None, validate_spaces=None)[source]¶

Get uptime settings.

Returns the Uptime app settings for the targeted space. You must have read privileges for the uptime feature in the Observability section of the Kibana feature privileges.

Parameters:

space_id (str | None) – Optional space ID to read the settings from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

heartbeatIndices: Index pattern used to query Heartbeat data (default "heartbeat-*")
certExpirationThreshold: Days before a certificate expires to trigger an alert (default 30)
certAgeThreshold: Days after a certificate is created to trigger an alert (default 730)
defaultConnectors: List of connector IDs used as default connectors for new alerts
defaultEmail: Default email configuration for new alerts (to/cc/bcc recipient lists)

Return type:

ObjectApiResponse containing the uptime settings

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to read the uptime settings.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> settings = client.uptime.get_settings()
>>> print(settings.body["heartbeatIndices"])
heartbeat-*
>>> print(settings.body["certExpirationThreshold"])
30

update_settings(*, heartbeat_indices=None, cert_expiration_threshold=None, cert_age_threshold=None, default_connectors=None, default_email=None, space_id=None, validate_spaces=None)[source]¶

Update uptime settings.

Updates the Uptime app settings for the targeted space. A partial update is supported: provided settings keys are merged with the existing settings and the full resulting settings object is returned. You must have all privileges for the uptime feature in the Observability section of the Kibana feature privileges.

Parameters:

heartbeat_indices (str | None) – An index pattern string to be used within the Uptime app and alerts to query Heartbeat data (default "heartbeat-*").
cert_expiration_threshold (float | None) – The number of days before a certificate expires to trigger an alert (default 30).
cert_age_threshold (float | None) – The number of days after a certificate is created to trigger an alert (default 730).
default_connectors (list[str] | None) – A list of connector IDs to be used as default connectors for new alerts.
default_email (dict[str, Any] | None) – The default email configuration for new alerts, an object with optional to, cc and bcc recipient lists, e.g. {"to": ["ops@example.com"], "cc": [], "bcc": []}.
space_id (str | None) – Optional space ID to update the settings in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the full updated uptime settings (same shape as get_settings()).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to update the uptime settings.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.uptime.update_settings(
...     heartbeat_indices="heartbeat-8*",
...     cert_expiration_threshold=14,
... )
>>> print(updated.body["heartbeatIndices"])
heartbeat-8*
>>> print(updated.body["certExpirationThreshold"])
14

perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]

AsyncUptimeClient¶

Asynchronous version of the UptimeClient for use with async/await syntax.

class kibana._async.client.uptime.AsyncUptimeClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: AsyncNamespaceClient

Async client for the Kibana Uptime API.

Reading the settings requires read privileges for the uptime feature in the Observability section of the Kibana feature privileges; updating them requires all privileges.

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Read the current settings
>>> settings = await client.uptime.get_settings()
>>> print(settings.body["heartbeatIndices"])
heartbeat-*
>>>
>>> # Partially update a single setting (other keys are preserved)
>>> updated = await client.uptime.update_settings(cert_age_threshold=365)
>>> print(updated.body["certAgeThreshold"])
365

Usage

The AsyncUptimeClient provides the same methods as UptimeClient but all methods are async and must be awaited:

from kibana import AsyncKibana
import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Read settings (async)
        settings = await client.uptime.get_settings()

        # Update settings (async)
        await client.uptime.update_settings(cert_age_threshold=365)

asyncio.run(main())

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the AsyncUptimeClient.

Parameters:

client (AsyncKibana) – The parent AsyncKibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> uptime_client = AsyncUptimeClient(kibana_client)

async get_settings(*, space_id=None, validate_spaces=None)[source]¶

Get uptime settings.

Returns the Uptime app settings for the targeted space. You must have read privileges for the uptime feature in the Observability section of the Kibana feature privileges.

Parameters:

space_id (str | None) – Optional space ID to read the settings from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

heartbeatIndices: Index pattern used to query Heartbeat data (default "heartbeat-*")
certExpirationThreshold: Days before a certificate expires to trigger an alert (default 30)
certAgeThreshold: Days after a certificate is created to trigger an alert (default 730)
defaultConnectors: List of connector IDs used as default connectors for new alerts
defaultEmail: Default email configuration for new alerts (to/cc/bcc recipient lists)

Return type:

ObjectApiResponse containing the uptime settings

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to read the uptime settings.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> settings = await client.uptime.get_settings()
>>> print(settings.body["heartbeatIndices"])
heartbeat-*
>>> print(settings.body["certExpirationThreshold"])
30

async update_settings(*, heartbeat_indices=None, cert_expiration_threshold=None, cert_age_threshold=None, default_connectors=None, default_email=None, space_id=None, validate_spaces=None)[source]¶

Update uptime settings.

Parameters:

heartbeat_indices (str | None) – An index pattern string to be used within the Uptime app and alerts to query Heartbeat data (default "heartbeat-*").
cert_expiration_threshold (float | None) – The number of days before a certificate expires to trigger an alert (default 30).
cert_age_threshold (float | None) – The number of days after a certificate is created to trigger an alert (default 730).
default_connectors (list[str] | None) – A list of connector IDs to be used as default connectors for new alerts.
default_email (dict[str, Any] | None) – The default email configuration for new alerts, an object with optional to, cc and bcc recipient lists, e.g. {"to": ["ops@example.com"], "cc": [], "bcc": []}.
space_id (str | None) – Optional space ID to update the settings in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the full updated uptime settings (same shape as get_settings()).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to update the uptime settings.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.uptime.update_settings(
...     heartbeat_indices="heartbeat-8*",
...     cert_expiration_threshold=14,
... )
>>> print(updated.body["heartbeatIndices"])
heartbeat-8*
>>> print(updated.body["certExpirationThreshold"])
14

async perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an async HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]