SyntheticsClient¶

Client for the Kibana Synthetics API.

Synthetics periodically checks the status of your services and applications from lightweight (HTTP, TCP, ICMP) and browser monitors. This client manages monitors, global parameters, and private locations, and can trigger on-demand test runs.

All Synthetics resources are space-scoped: 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).

Note

Creating a monitor requires at least one location: either an Elastic managed location (cloud) or a private location. Private locations are backed by a Fleet agent policy (agent_policy_id).

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

Bases: NamespaceClient

Client for the Kibana Synthetics API.

All Synthetics resources are space-scoped: 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).

Note

Creating a monitor requires at least one location: either an Elastic managed location (cloud) or a private location. Private locations are backed by a Fleet agent policy (agent_policy_id).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a private location, then an HTTP monitor using it
>>> loc = client.synthetics.create_private_location(
...     label="My private location",
...     agent_policy_id="abc-123",
... )
>>> monitor = client.synthetics.create_monitor(
...     type="http",
...     name="My monitor",
...     url="https://example.com",
...     private_locations=[loc.body["id"]],
... )
>>> client.synthetics.delete_monitor(id=monitor.body["id"])

Private Locations

from kibana import Kibana

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

# Create a private location backed by a Fleet agent policy
loc = client.synthetics.create_private_location(
    label="My private location",
    agent_policy_id="abc-123",
)
location_id = loc.body["id"]

# List private locations
locations = client.synthetics.get_private_locations()

Monitors

# Create an HTTP monitor running from the private location
monitor = client.synthetics.create_monitor(
    type="http",
    name="My monitor",
    url="https://example.com",
    private_locations=[location_id],
    schedule={"number": "5", "unit": "m"},
    tags=["production"],
)
monitor_id = monitor.body["id"]

# List monitors with filters
monitors = client.synthetics.get_monitors(
    monitor_types="http", tags="production"
)
for m in monitors.body["monitors"]:
    print(m["id"], m["name"])

# Update a monitor (partial update)
client.synthetics.update_monitor(
    id=monitor_id,
    enabled=False,
)

# Trigger an on-demand test run
test = client.synthetics.test_monitor(monitor_id=monitor_id)

# Delete the monitor
client.synthetics.delete_monitor(id=monitor_id)

Global Parameters

Global parameters can be referenced from monitor configurations (e.g. ${my_param}):

# Create a parameter
param = client.synthetics.create_param(
    key="base_url",
    value="https://example.com",
)

# List parameters
params = client.synthetics.get_params()

# Bulk delete parameters
client.synthetics.bulk_delete_params(ids=[param.body["id"]])

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

Initialize the SyntheticsClient.

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

>>> synthetics_client = SyntheticsClient(kibana_client)

get_monitors(*, filter=None, locations=None, monitor_types=None, page=None, per_page=None, projects=None, query=None, schedules=None, sort_field=None, sort_order=None, status=None, tags=None, use_logical_and_for=None, space_id=None, validate_spaces=None)[source]¶

Get monitors.

Get a paginated list of synthetics monitors, optionally filtered by type, location, tags, project, schedule or status.

Parameters:

filter (str | None) – Additional filtering criteria (KQL-style filter string).
locations (str | list[str] | None) – The location IDs to filter by.
monitor_types (str | list[str] | None) – The monitor types to filter by (http, tcp, icmp, browser).
page (int | None) – The page number for paginated results.
per_page (int | None) – The number of monitors to return per page. Sent to the server as perPage (the documented per_page name is rejected by Kibana 9.4.3).
projects (str | list[str] | None) – The project IDs to filter by.
query (str | None) – A free-text query string.
schedules (str | list[str] | None) – The schedules (in minutes) to filter by.
sort_field (str | None) – The field to sort by. Kibana 9.4.3 accepts enabled, status, updated_at, name.keyword, tags.keyword, project_id.keyword, type.keyword, schedule.keyword and journey_id (the documented name/createdAt/updatedAt values are rejected).
sort_order (str | None) – The sort order: asc or desc.
status (str | list[str] | None) – The monitor status to filter by (up, down).
tags (str | list[str] | None) – Tags to filter monitors by.
use_logical_and_for (str | list[str] | None) – Fields (tags, locations) that should be combined with logical AND instead of OR.
space_id (str | None) – Optional space ID to list monitors from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with monitors (list of monitor objects), page, perPage, total, absoluteTotal and syncErrors.

Raises:

BadRequestError – If a query parameter is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

SyntheticsClient¶

AsyncSyntheticsClient¶