AsyncKibana Client

The main asynchronous client for interacting with Kibana’s REST API using async/await syntax.

class kibana.AsyncKibana(hosts=None, *, cloud_id=None, api_key=None, basic_auth=None, bearer_auth=None, headers=<kibana._sync.client._base.DefaultType object>, request_timeout=<kibana._sync.client._base.DefaultType object>, verify_certs=<kibana._sync.client._base.DefaultType object>, ca_certs=<kibana._sync.client._base.DefaultType object>, client_cert=<kibana._sync.client._base.DefaultType object>, client_key=<kibana._sync.client._base.DefaultType object>, ssl_assert_hostname=<kibana._sync.client._base.DefaultType object>, ssl_assert_fingerprint=<kibana._sync.client._base.DefaultType object>, ssl_version=<kibana._sync.client._base.DefaultType object>, ssl_context=<kibana._sync.client._base.DefaultType object>, ssl_show_warn=<kibana._sync.client._base.DefaultType object>, max_retries=<kibana._sync.client._base.DefaultType object>, retry_on_status=<kibana._sync.client._base.DefaultType object>, retry_on_timeout=<kibana._sync.client._base.DefaultType object>, connections_per_node=<kibana._sync.client._base.DefaultType object>, dead_node_backoff_factor=<kibana._sync.client._base.DefaultType object>, max_dead_node_backoff=<kibana._sync.client._base.DefaultType object>, node_class=<kibana._sync.client._base.DefaultType object>, node_pool_class=<kibana._sync.client._base.DefaultType object>, randomize_nodes_in_pool=<kibana._sync.client._base.DefaultType object>, max_requests_per_second=None, _transport=None)[source]

Bases: AsyncBaseClient

Asynchronous client for Kibana.

Provides a Pythonic async interface to interact with Kibana’s REST APIs.

Example usage:
>>> from kibana import AsyncKibana
>>> client = AsyncKibana(
...     hosts=["http://localhost:5601"],
...     api_key="your_api_key"
... )
>>> # Use the client
>>> await client.close()
Or use as an async context manager:
>>> async with AsyncKibana(hosts=["http://localhost:5601"]) as client:
...     # Use the client
...     pass

Initialization

The AsyncKibana client can be initialized with the same options as the synchronous client:

from kibana import AsyncKibana

# Basic initialization with URL
client = AsyncKibana("http://localhost:5601")

# With API key authentication
client = AsyncKibana(
    "http://localhost:5601",
    api_key="your_api_key"
)

# With basic authentication
client = AsyncKibana(
    "http://localhost:5601",
    basic_auth=("username", "password")
)

Async Context Manager Usage

The async client should be used as an async context manager to ensure proper resource cleanup:

async with AsyncKibana("http://localhost:5601") as client:
    # Use the client with await
    status = await client.status.get_status()
    print(status.body["status"]["overall"]["level"])
# Client is automatically closed

Concurrent Operations

The async client enables concurrent operations for improved performance:

import asyncio
from kibana import AsyncKibana

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Execute multiple operations concurrently
        results = await asyncio.gather(
            client.actions.get_all(),
            client.spaces.get_all(),
            client.status.get_status()
        )
        actions, spaces, status = results

asyncio.run(main())

Namespace Clients

The AsyncKibana client provides access to various API namespaces through properties:

  • actions - Async Actions API for managing connectors

  • spaces - Async Spaces API for managing Kibana Spaces

  • saved_objects - Async Saved Objects API for managing saved objects

  • status - Async Status API for monitoring server health

All namespace client methods are async and must be awaited.

Space-Scoped Operations

Create a space-scoped async client for operations within a specific space:

# Create space-scoped client with validation
marketing_client = client.space("marketing")

# All operations are automatically scoped to the "marketing" space
connector = await marketing_client.actions.create(
    name="Marketing Webhook",
    connector_type_id=".webhook",
    config={"url": "https://example.com/webhook"}
)

# Create space-scoped client without validation (for performance)
fast_client = client.space("marketing", validate=False)
__init__(hosts=None, *, cloud_id=None, api_key=None, basic_auth=None, bearer_auth=None, headers=<kibana._sync.client._base.DefaultType object>, request_timeout=<kibana._sync.client._base.DefaultType object>, verify_certs=<kibana._sync.client._base.DefaultType object>, ca_certs=<kibana._sync.client._base.DefaultType object>, client_cert=<kibana._sync.client._base.DefaultType object>, client_key=<kibana._sync.client._base.DefaultType object>, ssl_assert_hostname=<kibana._sync.client._base.DefaultType object>, ssl_assert_fingerprint=<kibana._sync.client._base.DefaultType object>, ssl_version=<kibana._sync.client._base.DefaultType object>, ssl_context=<kibana._sync.client._base.DefaultType object>, ssl_show_warn=<kibana._sync.client._base.DefaultType object>, max_retries=<kibana._sync.client._base.DefaultType object>, retry_on_status=<kibana._sync.client._base.DefaultType object>, retry_on_timeout=<kibana._sync.client._base.DefaultType object>, connections_per_node=<kibana._sync.client._base.DefaultType object>, dead_node_backoff_factor=<kibana._sync.client._base.DefaultType object>, max_dead_node_backoff=<kibana._sync.client._base.DefaultType object>, node_class=<kibana._sync.client._base.DefaultType object>, node_pool_class=<kibana._sync.client._base.DefaultType object>, randomize_nodes_in_pool=<kibana._sync.client._base.DefaultType object>, max_requests_per_second=None, _transport=None)[source]

Initialize AsyncKibana client.

Parameters:

  • hosts (str | list[str | dict[str, Any]] | None) – List of Kibana nodes to connect to. Can be a single string or a list of strings/dicts. Examples: - “http://localhost:5601” - [”http://localhost:5601”, “http://localhost:5602”] - [{“host”: “localhost”, “port”: 5601, “scheme”: “http”}]

  • cloud_id (str | None) – Cloud ID for Elastic Cloud deployments

  • api_key (str | tuple[str, str] | None) – API key for authentication. Can be: - Base64-encoded string - Tuple of (id, api_key)

  • basic_auth (tuple[str, str] | None) – Basic authentication credentials as (username, password)

  • bearer_auth (str | None) – Bearer token for authentication

  • headers (DefaultType | Mapping[str, str]) – Custom headers to include in all requests

  • request_timeout (DefaultType | None | float) – Request timeout in seconds

  • verify_certs (DefaultType | bool) – Whether to verify SSL certificates

  • ca_certs (DefaultType | str) – Path to CA certificate bundle

  • client_cert (DefaultType | str) – Path to client certificate

  • client_key (DefaultType | str) – Path to client private key

  • ssl_assert_hostname (DefaultType | str) – Hostname to verify in SSL certificate

  • ssl_assert_fingerprint (DefaultType | str) – SSL certificate fingerprint to verify

  • ssl_version (DefaultType | int) – SSL/TLS version to use

  • ssl_context (DefaultType | Any) – Custom SSL context

  • ssl_show_warn (DefaultType | bool) – Whether to show SSL warnings

  • max_retries (DefaultType | int) – Maximum number of retries for failed requests

  • retry_on_status (DefaultType | list[int]) – HTTP status codes to retry on

  • retry_on_timeout (DefaultType | bool) – Whether to retry on timeout

  • connections_per_node (DefaultType | int) – Number of connections per node

  • dead_node_backoff_factor (DefaultType | float) – Backoff factor for dead nodes

  • max_dead_node_backoff (DefaultType | float) – Maximum backoff time for dead nodes

  • node_class (DefaultType | Any) – Custom node class

  • node_pool_class (DefaultType | Any) – Custom node pool class

  • randomize_nodes_in_pool (DefaultType | bool) – Whether to randomize node order

  • max_requests_per_second (float | None) – Optional rate limit (requests/sec). When set, outgoing requests are throttled using a token-bucket algorithm to prevent overwhelming the Kibana cluster.

  • _transport (AsyncTransport | None) – Pre-configured AsyncTransport instance (for testing)

async close()[source]

Close the client and release resources.

This closes all connections in the connection pool. After calling close(), the client should not be used.

async __aenter__()[source]

Enter async context manager.

async __aexit__(*args)[source]

Exit async context manager and close client.

property actions: AsyncActionsClient

Access the Actions API for managing Kibana action connectors.

Actions in Kibana are connectors that enable integration with external systems for alerting, notifications, and automation.

Returns:

AsyncActionsClient instance for managing action connectors

Example

>>> # Create a webhook connector
>>> connector = await client.actions.create(
...     name="Alert Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://example.com/webhook"}
... )

>>> # List all connectors
>>> connectors = await client.actions.get_all()

>>> # Execute a connector
>>> result = await client.actions.execute(
...     id=connector.body["id"],
...     params={"message": "Test alert"}
... )
property spaces: AsyncSpacesClient

Get the Spaces client for managing Kibana Spaces.

Returns:

AsyncSpacesClient instance

property status: AsyncStatusClient

Get the Status client for checking Kibana status.

Returns:

AsyncStatusClient instance

property saved_objects: AsyncSavedObjectsClient

Access the Saved Objects API for managing Kibana saved objects.

Saved Objects in Kibana are entities like dashboards, visualizations, index patterns, and other configuration items. This API provides methods to create, read, update, and delete saved objects.

Returns:

AsyncSavedObjectsClient instance for managing saved objects

Example

>>> # Create a dashboard
>>> dashboard = await client.saved_objects.create(
...     type="dashboard",
...     attributes={"title": "My Dashboard"}
... )

>>> # Get a saved object
>>> obj = await client.saved_objects.get(
...     type="dashboard",
...     id="my-dashboard-id"
... )

>>> # Update a saved object
>>> updated = await client.saved_objects.update(
...     type="dashboard",
...     id="my-dashboard-id",
...     attributes={"title": "Updated Dashboard"}
... )

>>> # Delete a saved object
>>> await client.saved_objects.delete(
...     type="dashboard",
...     id="my-dashboard-id"
... )
property alerting: AsyncAlertingClient

Access the Alerting API for managing rules.

Returns:

AsyncAlertingClient instance for managing rules.

space(space_id, validate=True)[source]

Create a space-scoped client instance.

This method creates a new client instance that automatically operates within the specified space context. All operations performed through the returned client will be scoped to the specified space.

Parameters:

  • space_id (str) – The ID of the space to scope operations to

  • validate (bool) – Whether to validate that the space exists (default: True)

Returns:

AsyncSpaceScopedKibana instance scoped to the specified space

Raises:
Return type:

AsyncSpaceScopedKibana

Example

>>> # Create a space-scoped client with validation
>>> marketing_client = await client.space("marketing")
>>>
>>> # Create connector in the marketing space
>>> connector = await marketing_client.actions.create(
...     name="Marketing Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://marketing.example.com/webhook"}
... )
>>>
>>> # Create space-scoped client without validation (for performance)
>>> fast_client = await client.space("marketing", validate=False)
__repr__()[source]

Return string representation of client.

options(*, api_key=<kibana._sync.client._base.DefaultType object>, basic_auth=<kibana._sync.client._base.DefaultType object>, bearer_auth=<kibana._sync.client._base.DefaultType object>, headers=<kibana._sync.client._base.DefaultType object>, request_timeout=<kibana._sync.client._base.DefaultType object>)

Create a new client instance with modified options.

This allows per-request configuration without modifying the original client.

Parameters:

  • api_key (DefaultType | str | tuple[str, str]) – API key for authentication

  • basic_auth (DefaultType | tuple[str, str]) – Basic auth credentials (username, password)

  • bearer_auth (DefaultType | str) – Bearer token for authentication

  • headers (DefaultType | Mapping[str, str]) – Custom headers to include in requests

  • request_timeout (DefaultType | float) – Request timeout in seconds

Returns:

New AsyncBaseClient instance with updated options

Return type:

AsyncBaseClient

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

Perform an async HTTP request to Kibana.

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

Return type:

ObjectApiResponse[Any]

AsyncSpaceScopedKibana

A space-scoped async client that automatically operates within a specific space context.

class kibana._async.client.AsyncSpaceScopedKibana(client, space_id, validate=True)[source]

Bases: object

Space-scoped async client that delegates to main client with space context.

This class provides the same API surface as the main AsyncKibana client but automatically scopes all operations to a specific space. All child clients (actions, saved_objects, etc.) created through this instance will inherit the space context and validation settings.

Example

>>> # Create space-scoped client with validation
>>> marketing_client = client.space("marketing")
>>>
>>> # All operations are automatically scoped to "marketing" space
>>> connector = await marketing_client.actions.create(
...     name="Marketing Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://marketing.example.com/webhook"}
... )
>>>
>>> # Create space-scoped client without validation for performance
>>> fast_client = client.space("marketing", validate=False)

Usage

Space-scoped async clients are created using the AsyncKibana.space() method:

# Create space-scoped client
marketing_client = client.space("marketing")

# All operations inherit the space context and must be awaited
connector = await marketing_client.actions.create(
    name="Test Connector",
    connector_type_id=".index",
    config={"index": "test"}
)

# The connector is created in the "marketing" space
# No need to pass space_id parameter

Async Context Manager

Space-scoped async clients can also be used as async context managers:

async with client.space("marketing") as marketing_client:
    # Perform operations in the marketing space
    connector = await marketing_client.actions.create(
        name="Test Connector",
        connector_type_id=".index",
        config={"index": "test"}
    )
# Client is automatically closed

Validation

By default, space-scoped clients validate that the space exists. For async clients, validation happens on first use rather than at creation time:

# With validation (default) - validated on first operation
client_with_validation = client.space("marketing")

# Without validation (faster, but may fail on operations if space doesn't exist)
client_without_validation = client.space("marketing", validate=False)
__init__(client, space_id, validate=True)[source]

Initialize space-scoped async client.

Parameters:

  • client (AsyncKibana) – The main AsyncKibana client to delegate to

  • space_id (str) – The space ID to scope operations to

  • validate (bool) – Whether to validate that the space exists

Raises:

SpaceNotFoundError – If validate=True and the space doesn’t exist

property actions: AsyncActionsClient

Get AsyncActionsClient with space scope.

Returns an AsyncActionsClient instance that automatically operates within the space context of this AsyncSpaceScopedKibana instance.

Returns:

AsyncActionsClient scoped to this space

Example

>>> marketing_client = client.space("marketing")
>>> # This connector will be created in the "marketing" space
>>> connector = await marketing_client.actions.create(
...     name="Marketing Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://marketing.example.com/webhook"}
... )
property saved_objects: AsyncSavedObjectsClient

Get AsyncSavedObjectsClient with space scope.

Returns an AsyncSavedObjectsClient instance that automatically operates within the space context of this AsyncSpaceScopedKibana instance.

Returns:

AsyncSavedObjectsClient scoped to this space

Example

>>> marketing_client = client.space("marketing")
>>> # This dashboard will be created in the "marketing" space
>>> dashboard = await marketing_client.saved_objects.create(
...     type="dashboard",
...     attributes={"title": "Marketing Dashboard"}
... )
property spaces: AsyncSpacesClient

Get AsyncSpacesClient (not space-scoped).

The AsyncSpacesClient is used for managing spaces themselves and is not scoped to a particular space. It uses the same client as the parent AsyncKibana instance.

Returns:

AsyncSpacesClient for managing spaces

property status: AsyncStatusClient

Get AsyncStatusClient (not space-scoped).

The AsyncStatusClient provides server-wide status information and is not scoped to a particular space. It uses the same client as the parent AsyncKibana instance.

Returns:

AsyncStatusClient for monitoring server status

async close()[source]

Close the underlying client and release resources.

This delegates to the main AsyncKibana client’s close() method.

async __aenter__()[source]

Enter async context manager.

async __aexit__(*args)[source]

Exit async context manager and close client.

__repr__()[source]

Return string representation of space-scoped client.