Kibana Python Client

Disclaimer: This is an independent, community-driven project and is not officially affiliated with, endorsed by, or supported by Elastic N.V. or any of its subsidiaries. "Kibana" and "Elasticsearch" are trademarks of Elastic N.V. This project is provided "as is", without warranty of any kind. Use it at your own risk. See the Disclaimer section and the LICENSE for full details.

A Python client library for the Kibana REST API with complete platform, Fleet, and Security Solution API coverage — 39 namespaces, 610 endpoints, sync and async. Built following the design patterns of the elasticsearch-py client, and verified live against Kibana 9.5.4 and 9.4.7 — see Version support.

Headline feature: first-class support for the new Kibana Dashboards HTTP API (client.dashboards, technical preview in 9.4) and its sibling Visualizations HTTP API (client.visualizations) — manage dashboards and Lens visualizations through a real, documented data model instead of opaque saved objects.

📚 Documentation

Read the full documentation on ReadTheDocs →

• Installation Guide
• Quick Start Guide
• User Guide
• API Reference
• Examples

Features

• Complete API coverage: 39 namespaces, 610 endpoints spanning the Kibana platform, Fleet, and Security Solution REST APIs, every one live-tested against a real Kibana
• Two Kibana lines, one contract: the same code runs on Kibana 9.5.x and 9.4.x. Where the server renamed a response between lines, the client carries both names; where an endpoint was removed, it says so instead of returning a bare 404. See Version support
• Fleet & Security Solution: full clients for Fleet (agents, policies, integrations/EPM, outputs, enrollment) and Security Solution (detection engine, exceptions, value lists, timelines, endpoint response actions, entity analytics, osquery, AI assistant, attack discovery)
• New Dashboards & Visualizations APIs: first-class clients for the tech-preview Dashboards and Lens Visualizations HTTP APIs introduced in Kibana 9.4
• Dual API support: synchronous (Kibana) and asynchronous (AsyncKibana) clients with full method parity
• NDJSON & multipart: saved-object export (application/x-ndjson) parsing and multipart/form-data uploads (saved-object import, APM source maps)
• Type safety: comprehensive type hints throughout, py.typed marker (PEP 561)
• Reliable transport: built on elastic-transport for connection pooling, retries, and node management; SSL/TLS options (verify_certs, ca_certs, client certs, custom contexts) fully honored
• Flexible authentication: API keys, basic auth, and bearer tokens
• Space support: multi-tenancy with Kibana Spaces — space-scoped clients and per-call space_id
• Comprehensive error handling: specific exception types per HTTP status, carrying Kibana's detailed error message
• Observability: built-in OpenTelemetry support for distributed tracing

Installation

pip install kibana-py

Requires Python 3.11+.

Optional dependencies:

• kibana-py[async] - Async client support
• kibana-py[orjson] - High-performance JSON serialization
• kibana-py[observability] - OpenTelemetry tracing support

For detailed installation instructions, see the Installation Guide.

Quick Start

Dashboards (new HTTP API, Kibana 9.4+)

from kibana import Kibana

client = Kibana(
    "http://localhost:5601",
    basic_auth=("elastic", "password"),
)

# Create a dashboard with a markdown panel and a relative time range
dashboard = client.dashboards.create(
    title="Service health",
    description="Ops overview",
    time_range={"from": "now-24h", "to": "now"},
    panels=[
        {
            "type": "markdown",
            "grid": {"x": 0, "y": 0, "w": 48, "h": 6},
            "config": {"content": "## Runbook links"},
        }
    ],
)
dashboard_id = dashboard.body["id"]

# Search dashboards, then fetch the full panel layout of one
results = client.dashboards.get_all(query="service*", per_page=10)
print(f"Found {results.body['total']} dashboards")

full = client.dashboards.get(id=dashboard_id)
print(full.body["data"]["title"])

# Clean up
client.dashboards.delete(id=dashboard_id)
client.close()

Connectors

from kibana import Kibana

with Kibana("http://localhost:5601", basic_auth=("elastic", "password")) as client:
    connector = client.connectors.create(
        name="My Webhook",
        connector_type_id=".webhook",
        config={"url": "https://example.com/webhook"},
    )
    print(f"Created connector: {connector.body['id']}")

Deprecation note: the connectors namespace was previously exposed as client.actions. client.actions still works as a deprecated alias of client.connectors and will be removed in a future release — new code should use client.connectors.

Async Client

import asyncio
from kibana import AsyncKibana

async def main():
    async with AsyncKibana(
        "http://localhost:5601",
        basic_auth=("elastic", "password")
    ) as client:
        status = await client.status.get_status()
        print(status.body["status"]["overall"]["level"])

asyncio.run(main())

For more examples and detailed usage, see:

• Quick Start Guide
• User Guide
• Examples

API Coverage

Full coverage of the Kibana platform, Fleet, and Security Solution REST APIs — 39 namespaces, 610 endpoints, identical sync and async surfaces, live-tested on every supported version.

Platform (24 namespaces, 269 endpoints)

Fleet (6 namespaces, 140 endpoints)

Security Solution (9 namespaces, 201 endpoints)

¹ Some endpoints in this namespace are technical preview in Kibana 9.4 (e.g. Agent Builder consumption/skills/plugins, cases custom-field/template features, status.get_features()).

² Most single-object and bulk saved-object CRUD endpoints are deprecated by Kibana 9.4 in favor of the type-specific APIs (dashboards, data views, ...) and the export/import APIs; the client methods carry deprecation notes with replacements.

³ Entity analytics spans several maturity levels in Kibana 9.4: asset-criticality endpoints are deprecated (superseded by the entity store), watchlists and privileged-user monitoring are technical preview, and the risk-score engine and entity store are GA. Method docstrings note the per-endpoint state and any live-server behavior that differs from the OpenAPI spec.

For detailed API documentation, see the API Reference.

Health Checks & Readiness Probes

Use the Status API to build health check endpoints for Kubernetes liveness/readiness probes or load-balancer health checks:

from kibana import Kibana

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

# Simple health check
def is_kibana_ready() -> bool:
    """Return True if Kibana is green/ready."""
    try:
        status = client.status.get_status()
        return status.body["status"]["overall"]["level"] == "available"
    except Exception:
        return False

# Kubernetes-style probe endpoint (Flask example)
@app.route("/healthz")
def healthz():
    if is_kibana_ready():
        return {"status": "ok"}, 200
    return {"status": "unavailable"}, 503

Authentication

The client supports multiple authentication methods:

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

# Basic Auth
client = Kibana("http://localhost:5601", basic_auth=("username", "password"))

# Bearer Token
client = Kibana("http://localhost:5601", bearer_auth="your_token")

For more details, see the Authentication Guide.

Examples

The examples/ directory contains a runnable <namespace>_management.py walkthrough for every namespace — dashboards, visualizations, alerting, cases, connectors, streams, workflows, agent builder, and the rest — plus quick-start, async, and error-handling examples. See examples/README.md for the full catalog.

See the Examples Documentation for detailed explanations.

Development

Contributions are welcome! See the Contributing Guide for details on:

• Setting up your development environment
• Running tests
• Code style and quality standards
• Submitting pull requests

For more information, see the Development Documentation.

Requirements

• Python 3.11+
• Kibana — see Version support below
• elastic-transport >= 9.1.0

Version support

The client targets the two most recent Kibana minor lines, at the latest patch of each, and is tested live against both. Older patches of a supported line are expected to work but are not tested.

The 9.4.7 and 9.5.4 patches changed four Fleet routes in lockstep — an unknown agent's uploads and an unknown agentless policy delete are now 404s, message-signing rotation requires superuser, and an upload install refuses a package name the registry already carries. Both lines agree, so no caller code needs a version branch; callers relying on the old answers need to know. Details in the CHANGELOG and the evidence file linked below.

Supported and release-gated are the same list, by construction: the set is declared once in kibana/_compat.py, and both the integration-probe workflow and the release gate build their matrix from it. A line the gate does not run is not a line the README can claim.

One contract across both lines

Kibana changes API shapes between minor lines. The client absorbs those changes so the same code runs on both, and it does so additively — it never removes, renames, or overwrites what the server sent:

• dashboards.get_all() — 9.5 rewrapped the search envelope. The response carries both spellings on both lines: body["dashboards"] / body["page"] / body["total"] (the 9.4 names) and body["data"] / body["meta"] (the 9.5 names). The list is the same object under either name.
• streams.get_significant_events() — 9.5 renamed significant_events to queries. Both names are present on both lines.
• streams.upsert() — the one request in the client that varies by server version. 9.4 requires a queries field in the stream body; 9.5 rejects it as an excess key. No single body satisfies both, so the client supplies the field where it is required and omits it where it is not: an upsert that does not mention queries succeeds on both lines, unchanged from before on 9.4. Passing queries explicitly against 9.5 raises rather than silently dropping your input, and points at upsert_query(), bulk_queries() and delete_query() — which work on every supported line.

Capabilities that exist on only one line

Kibana 9.5 removed two significant-events endpoints from the public API, replacing them with an internal, unversioned surface this client deliberately does not call; and it stopped accepting the queries field described above. Using any of the three against 9.5 raises KibanaVersionError before any request is sent, rather than returning a 404 that reads like a missing stream or a 400 about a field you did not know was contested:

Asking the client what it is talking to

from kibana import Kibana, is_supported, SUPPORTED_VERSIONS

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

client.server_version()              # '9.5.4' — one lazy request, cached
is_supported(client.server_version())  # True
SUPPORTED_VERSIONS                   # (('9.5', '9.5.4'), ('9.4', '9.4.7'))

await client.server_version() on the async client. Nothing queries /api/status until something asks, and the answer is resolved once per client.

The client does not refuse to talk to an unsupported Kibana. It has measured nothing about one, so it makes no claim: calls behave exactly as they would without any of this.

Moving the set forward

The policy, the procedure, the criteria for dropping the oldest line, and the dated record of every decision are in Kibana version support (docs/source/development/version-support.md). make versions checks that every version statement in the repository agrees with the one source, and python3 scripts/checks/supported-versions.py --latest asks the Elastic registry whether the pins are still the newest patches.

Measurements, method, and the full per-version diff: docs/evidence/multi-version-9.4.7-9.5.4.md, and the move that introduced the two-line contract in docs/evidence/multi-version-9.4.5-9.5.2.md.

Resources

• Documentation - Complete documentation on ReadTheDocs
• Examples - Working code examples
• Contributing - Contribution guidelines
• Maintainers - Maintainer ownership and release responsibilities
• Code of Conduct - Community participation standards
• Changelog - Release history
• Issue Tracker - Report bugs or request features
• Kibana API Docs - Official Kibana API documentation

Disclaimer

This project is an independent, community-driven open-source effort. It is not officially affiliated with, endorsed by, sponsored by, or supported by Elastic N.V. or any of its subsidiaries. "Kibana", "Elasticsearch", and "Elastic" are trademarks or registered trademarks of Elastic N.V.

This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors, contributors, or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

By using this library, you acknowledge that:

• The authors and contributors assume no responsibility or liability for any errors, issues, data loss, or damages resulting from the use of this software.
• You are solely responsible for evaluating the suitability of this software for your use case and for any consequences of its use.
• This project is not a substitute for Elastic's official tools, clients, or support channels.

For the complete license terms, see the LICENSE file.

License

Apache License 2.0 - See LICENSE for details.