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. Each API group is exposed as a namespace attribute (client.dashboards, client.spaces, client.alerting, …), mirroring the structure of the official Kibana API reference.

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)

actions: AsyncActionsClient¶

agent_builder: AsyncAgentBuilderClient¶

alerting: AsyncAlertingClient¶

apm: AsyncApmClient¶

attack_discovery: AsyncAttackDiscoveryClient¶

cases: AsyncCasesClient¶

connectors: AsyncConnectorsClient¶

dashboards: AsyncDashboardsClient¶

data_views: AsyncDataViewsClient¶

detection_engine: AsyncDetectionEngineClient¶

endpoint: AsyncEndpointClient¶

entity_analytics: AsyncEntityAnalyticsClient¶

exception_lists: AsyncExceptionListsClient¶

fleet: AsyncFleetClient¶

fleet_agents: AsyncFleetAgentsClient¶

fleet_enrollment: AsyncFleetEnrollmentClient¶

fleet_epm: AsyncFleetEpmClient¶

fleet_outputs: AsyncFleetOutputsClient¶

fleet_policies: AsyncFleetPoliciesClient¶

lists: AsyncListsClient¶

logstash: AsyncLogstashClient¶

maintenance_windows: AsyncMaintenanceWindowsClient¶

ml: AsyncMlClient¶

observability_ai_assistant: AsyncObservabilityAiAssistantClient¶

osquery: AsyncOsqueryClient¶

saved_objects: AsyncSavedObjectsClient¶

security: AsyncSecurityClient¶

security_ai_assistant: AsyncSecurityAiAssistantClient¶

short_urls: AsyncShortUrlsClient¶

slos: AsyncSlosClient¶

spaces: AsyncSpacesClient¶

status: AsyncStatusClient¶

streams: AsyncStreamsClient¶

synthetics: AsyncSyntheticsClient¶

task_manager: AsyncTaskManagerClient¶

timeline: AsyncTimelineClient¶

upgrade_assistant: AsyncUpgradeAssistantClient¶

uptime: AsyncUptimeClient¶

visualizations: AsyncVisualizationsClient¶

workflows: AsyncWorkflowsClient¶

__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.

async 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.

Changed in version 0.2.0: This method is now a coroutine so that validate=True can actually check the space against the server (previously the check was silently skipped). Call it as await client.space("id").

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:

SpaceNotFoundError – If validate=True and the space doesn’t exist
InvalidSpaceIdError – If the space_id format is invalid

Return type:

AsyncSpaceScopedKibana

Example

>>> # Create a space-scoped client with validation
>>> marketing_client = await client.space("marketing")
>>>
>>> # Create a dashboard in the marketing space
>>> dashboard = await marketing_client.dashboards.create(
...     title="Marketing KPIs"
... )
>>>
>>> # 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:

Self

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 (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 (dashboards, saved_objects, alerting, etc.) created through this instance inherit the space context and validation settings. Namespaces that are not space-aware (spaces, status, security, task_manager, upgrade_assistant, logstash) delegate to the parent client unscoped.

Example

>>> # Create space-scoped client with validation
>>> marketing_client = await client.space("marketing")
>>>
>>> # All operations are automatically scoped to "marketing" space
>>> dashboard = await marketing_client.dashboards.create(
...     title="Marketing KPIs"
... )
>>>
>>> # Create space-scoped client without validation for performance
>>> fast_client = await 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)