DashboardsClient¶

Client for the new Kibana Dashboards HTTP API.

Note

The Dashboards HTTP API is in technical preview (added in Kibana 9.4.0) and may change in future releases.

The Dashboards API manages dashboards as code: each dashboard is addressed by its ID and represented by a flat data object. Responses are enveloped as {"id": ..., "data": {...}, "meta": {...}} where meta carries server-managed fields (created_at, updated_at, created_by, updated_by, managed, version).

Dashboards are space-scoped: every method accepts space_id to target a specific Kibana space, or you can use a space-scoped client created with client.space("my-space").

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

Bases: NamespaceClient

Client for the Kibana Dashboards HTTP API.

Technical preview in 9.4 (added in 9.4.0). The Dashboards API manages dashboards as code: each dashboard is addressed by its ID and represented by a flat data object. Responses are enveloped as {"id": ..., "data": {...}, "meta": {...}} where meta carries server-managed fields (created_at, updated_at, created_by, updated_by, managed, version).

The dashboard data model (the data object) supports:

title (required): human-readable dashboard title.
description: short description of the dashboard.
panels: list of panels and collapsible sections. Each panel has a type (e.g. "markdown", "vis", "image", "discover_session", control panels, SLO/synthetics/APM embeddables), a grid placement (x, y required; w up to 48, defaults 24; h defaults 15) and a type-specific config (either inline “by value” or ref_id “by reference”). Sections are objects with a title, collapsed flag and nested panels.
options: display/behavior settings (auto_apply_filters, hide_panel_borders, hide_panel_titles, sync_colors, sync_cursor, sync_tooltips, use_margins).
filters: filters applied across all panels (simple condition filters, DSL filters, group filters or spatial filters).
query: a search query {"expression": ..., "language": "kql" | "lucene"} applied to the dashboard.
time_range: {"from": ..., "to": ..., "mode": "absolute" | "relative"} accepting date math (e.g. now-7d) or ISO 8601 timestamps.
refresh_interval: {"pause": bool, "value": ms} auto-refresh setting.
tags: list of tag IDs associated with the dashboard.
pinned_panels: control panels and their state in the control group.
access_control: {"access_mode": "default" | "write_restricted"} edit-access setting. Accepted only at creation time (create()); PUT rejects it.
project_routing: cross-project search routing behavior.

Dashboards are space-scoped: every method accepts space_id to target a specific Kibana space (None targets the default space or the client’s default space).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a dashboard with a markdown panel
>>> dashboard = client.dashboards.create(
...     title="Team Overview",
...     panels=[
...         {
...             "type": "markdown",
...             "grid": {"x": 0, "y": 0, "w": 24, "h": 15},
...             "config": {"content": "# Welcome", "settings": {}},
...         }
...     ],
... )
>>> dashboard_id = dashboard.body["id"]
>>>
>>> # Search dashboards
>>> results = client.dashboards.get_all(query="Team*")
>>> for item in results.body["dashboards"]:
...     print(item["id"], item["data"]["title"])

Overview

The DashboardsClient provides methods to create, retrieve, search, update (upsert), and delete dashboards through the /api/dashboards endpoints.

The Dashboard Data Model

The data object supports:

title (required) - human-readable dashboard title
description - short description of the dashboard
panels - list of panels and collapsible sections; each panel has a type (e.g. "markdown", "vis", "image", "discover_session"), a grid placement (x, y required; w up to 48, defaults 24; h defaults 15) and a type-specific config (inline “by value” or ref_id “by reference”)
options - display/behavior settings (auto_apply_filters, hide_panel_borders, hide_panel_titles, sync_colors, sync_cursor, sync_tooltips, use_margins)
filters - filters applied across all panels
query - a search query {"expression": ..., "language": "kql" | "lucene"}
time_range - {"from": ..., "to": ...} accepting date math (e.g. now-7d) or ISO 8601 timestamps
refresh_interval - {"pause": bool, "value": ms} auto-refresh setting
tags - list of tag IDs associated with the dashboard
pinned_panels - control panels and their state in the control group
access_control - {"access_mode": "default" | "write_restricted"} edit-access setting; accepted only at creation time (create())

Creating Dashboards

Create a dashboard with the create() method. The server assigns the dashboard ID:

from kibana import Kibana

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

# Create a dashboard with a markdown panel, tags and a time range
created = client.dashboards.create(
    title="Team Overview",
    description="Key metrics for the team",
    tags=["team-tag-id"],
    time_range={"from": "now-7d", "to": "now"},
    panels=[
        {
            "type": "markdown",
            "grid": {"x": 0, "y": 0, "w": 48, "h": 8},
            "config": {
                "title": "Welcome",
                "content": "# Team Overview\nManaged by *kibana-py*.",
                "settings": {"open_links_in_new_tab": True},
            },
        }
    ],
)

dashboard_id = created.body["id"]
print(f"Created dashboard: {dashboard_id}")

Retrieving Dashboards

Read a dashboard back with get(). Responses are {id, data, meta} envelopes:

fetched = client.dashboards.get(id=dashboard_id)

data = fetched.body["data"]
print(f"Title: {data['title']}")
print(f"Panels: {[p['type'] for p in data['panels']]}")
print(f"Updated at: {fetched.body['meta']['updated_at']}")

Searching Dashboards

List and filter dashboards with get_all(). The query parameter filters on title and description using Elasticsearch simple_query_string syntax:

# Search dashboards with query/tags filters and pagination
results = client.dashboards.get_all(
    query="Team*",
    tags=["team-tag-id"],
    per_page=10,
    page=1,
)

print(f"Total matches: {results.body['total']}")
for item in results.body["dashboards"]:
    print(item["id"], item["data"]["title"])

Updating (Upserting) Dashboards

update() performs an upsert via PUT /api/dashboards/{id}: if the dashboard exists it is replaced with the provided data; if it does not exist it is created with the given ID. This is also the way to create a dashboard with a custom ID, since create() always assigns a server-generated ID:

# Replace an existing dashboard (omitted fields revert to defaults)
client.dashboards.update(
    id=dashboard_id,
    title="Team Overview (v2)",
    time_range={"from": "now-30d", "to": "now"},
)

# Upsert a dashboard at a custom ID
client.dashboards.update(
    id="my-well-known-dashboard-id",
    title="Provisioned Dashboard",
)

Warning

The provided data replaces the stored dashboard data — fields omitted from the call revert to their defaults rather than being preserved. Unlike create(), update does not accept an access_control field; access control can only be set at creation time.

Deleting Dashboards

client.dashboards.delete(id=dashboard_id)

Space-Scoped Dashboards

Dashboards live inside Kibana spaces:

# Target a space explicitly
dashboard = client.dashboards.create(
    title="Marketing KPIs",
    space_id="marketing",
)

# Or use a space-scoped client
marketing = client.space("marketing")
dashboard = marketing.dashboards.create(title="Marketing KPIs")

Error Handling

from kibana.exceptions import (
    NotFoundError,
    BadRequestError,
    SpaceNotFoundError,
)

try:
    dashboard = client.dashboards.get(id="nonexistent")
except NotFoundError:
    print("Dashboard not found")
except BadRequestError as e:
    print(f"Invalid request: {e.message}")
except SpaceNotFoundError as e:
    print(f"Space not found: {e.space_id}")

get_all(*, page=None, per_page=None, query=None, tags=None, excluded_tags=None, space_id=None, validate_spaces=None)[source]¶

Search dashboards.

Technical preview in 9.4. Returns a paginated list of dashboards matching the search criteria. Each list entry contains summary fields (title, description, tags, time_range, access_control) but not the full panel layout — use get() to retrieve a complete dashboard.

Parameters:

page (int | None) – The page of results to return. Defaults to 1.
per_page (int | None) – The number of results to return per page. Defaults to 20.
query (str | None) – Filters results by title and description using Elasticsearch simple_query_string syntax (e.g. "sales*"). Multi-word terms are OR-ed by default.
tags (list[str] | None) – Tag IDs to include. When multiple are specified, dashboards matching any of the tag IDs are included (max 100).
excluded_tags (list[str] | None) – Tag IDs to exclude. When multiple are specified, dashboards matching any of the tag IDs are excluded (max 100).
space_id (str | None) – Optional space ID to search dashboards in. None targets the default space (or the client’s default space).
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body contains dashboards (a list of {"id", "data", "meta"} envelopes) plus page and total pagination fields.

Raises:

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

Return type:

ObjectApiResponse[Any]

Example

>>> results = client.dashboards.get_all(
...     query="sales*",
...     tags=["tag-id-1"],
...     per_page=10,
...     page=1,
... )
>>> print(results.body["total"])
>>> for item in results.body["dashboards"]:
...     print(item["id"], item["data"]["title"])

create(*, title, description=None, panels=None, options=None, filters=None, query=None, time_range=None, refresh_interval=None, tags=None, pinned_panels=None, access_control=None, project_routing=None, space_id=None, validate_spaces=None)[source]¶

Create a dashboard.

Technical preview in 9.4. Creates a dashboard with a server-assigned ID. The request body is the flat dashboard data object; the server rejects an id property in the body and assigns one itself. To create a dashboard with a custom ID, use update(), which performs an upsert on PUT /api/dashboards/{id}.

Parameters:

title (str) – A human-readable title for the dashboard (required).
description (str | None) – A short description of the dashboard.
panels (list[dict[str, Any]] | None) – Panels and sections. Each panel is a dict with type (e.g. "markdown", "vis", "image"), grid ({"x", "y"} required, optional "w" <= 48 and "h") and a type-specific config (inline config or {"ref_id": ...} for library items). A section is a dict with title, collapsed and nested panels.
options (dict[str, Any] | None) – Display and behavior settings, e.g. {"hide_panel_titles": True, "use_margins": False}. Unspecified keys keep their server defaults.
filters (list[dict[str, Any]] | None) – Filters applied across all panels, including pinned panels (condition, DSL, group or spatial filters).
query (dict[str, Any] | None) – Search query, e.g. {"expression": "status:active", "language": "kql"} (language is "kql" or "lucene").
time_range (dict[str, Any] | None) – Time range, e.g. {"from": "now-7d", "to": "now", "mode": "relative"}. from/to accept date math or ISO 8601 timestamps.
refresh_interval (dict[str, Any] | None) – Auto-refresh setting {"pause": bool, "value": milliseconds}.
tags (list[str] | None) – Tag IDs to associate with this dashboard (max 100).
pinned_panels (list[dict[str, Any]] | None) – Control panels and their state in the control group.
access_control (dict[str, Any] | None) – Access control settings, e.g. {"access_mode": "write_restricted"} to prevent edits by users without explicit write permission. Only settable at creation time — PUT /api/dashboards/{id} (update()) rejects this field. Requires an identifiable user profile: under plain basic auth the server responds 400 (“Kibana could not determine the user profile ID for the caller”).
project_routing (str | None) – Cross-project search routing behavior for the dashboard.
space_id (str | None) – Optional space ID to create the dashboard in.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body is an {"id", "data", "meta"} envelope for the created dashboard.

Raises:

ValueError – If title is missing.
BadRequestError – If the dashboard data fails schema validation (including passing an id field via panels etc.).
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> dashboard = client.dashboards.create(
...     title="Service health",
...     description="Ops overview",
...     tags=["ops-tag-id"],
...     time_range={"from": "now-24h", "to": "now"},
...     panels=[
...         {
...             "type": "markdown",
...             "grid": {"x": 0, "y": 0, "w": 48, "h": 6},
...             "config": {
...                 "content": "## Runbook links",
...                 "settings": {"open_links_in_new_tab": True},
...             },
...         }
...     ],
... )
>>> print(dashboard.body["id"])

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

Get a dashboard by ID.

Technical preview in 9.4. Retrieves the full dashboard, including its complete panel layout.

Parameters:

id (str) – The dashboard ID to retrieve.
space_id (str | None) – Optional space ID to get the dashboard from.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body is an {"id", "data", "meta"} envelope.

Raises:

ValueError – If id is missing.
NotFoundError – If the dashboard does not exist.
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> dashboard = client.dashboards.get(id="my-dashboard")
>>> print(dashboard.body["data"]["title"])
>>> for panel in dashboard.body["data"]["panels"]:
...     print(panel["type"], panel["grid"])

update(*, id, title, description=None, panels=None, options=None, filters=None, query=None, time_range=None, refresh_interval=None, tags=None, pinned_panels=None, project_routing=None, space_id=None, validate_spaces=None)[source]¶

Update (upsert) a dashboard by ID.

Technical preview in 9.4. PUT /api/dashboards/{id} is an upsert: if the dashboard exists it is replaced with the provided data (the server responds 200); if it does not exist it is created with the given ID (the server responds 201). This is the way to create a dashboard with a custom ID, since create() always assigns a server-generated ID and rejects an id in the body.

Note that the provided data replaces the stored dashboard data — fields omitted from the call revert to their defaults rather than being preserved.

Unlike create(), this endpoint does not accept an access_control field — access control can only be set at creation time, and the server rejects it in a PUT body with a 400 error.

Parameters:

id (str) – The dashboard ID to update or create.
title (str) – A human-readable title for the dashboard (required).
description (str | None) – A short description of the dashboard.
panels (list[dict[str, Any]] | None) – Panels and sections. Each panel is a dict with type (e.g. "markdown", "vis", "image"), grid ({"x", "y"} required, optional "w" <= 48 and "h") and a type-specific config (inline config or {"ref_id": ...} for library items). A section is a dict with title, collapsed and nested panels.
options (dict[str, Any] | None) – Display and behavior settings, e.g. {"hide_panel_titles": True, "use_margins": False}.
filters (list[dict[str, Any]] | None) – Filters applied across all panels, including pinned panels (condition, DSL, group or spatial filters).
query (dict[str, Any] | None) – Search query, e.g. {"expression": "status:active", "language": "kql"} (language is "kql" or "lucene").
time_range (dict[str, Any] | None) – Time range, e.g. {"from": "now-7d", "to": "now", "mode": "relative"}. from/to accept date math or ISO 8601 timestamps.
refresh_interval (dict[str, Any] | None) – Auto-refresh setting {"pause": bool, "value": milliseconds}.
tags (list[str] | None) – Tag IDs to associate with this dashboard (max 100).
pinned_panels (list[dict[str, Any]] | None) – Control panels and their state in the control group.
project_routing (str | None) – Cross-project search routing behavior for the dashboard.
space_id (str | None) – Optional space ID where the dashboard lives.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body is an {"id", "data", "meta"} envelope for the updated or newly created dashboard.

Raises:

ValueError – If id or title is missing.
BadRequestError – If the dashboard data fails schema validation.
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> # Create a dashboard with a custom ID (upsert)
>>> dashboard = client.dashboards.update(
...     id="team-overview",
...     title="Team Overview",
... )
>>>
>>> # Replace its content later
>>> dashboard = client.dashboards.update(
...     id="team-overview",
...     title="Team Overview v2",
...     tags=["team-tag-id"],
... )

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

Delete a dashboard by ID.

Technical preview in 9.4. Permanently deletes the dashboard. The server responds 204 with an empty body on success.

Parameters:

id (str) – The dashboard ID to delete.
space_id (str | None) – Optional space ID to delete the dashboard from.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse, empty for successful deletion (HTTP 204).

Raises:

ValueError – If id is missing.
NotFoundError – If the dashboard does not exist.
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> client.dashboards.delete(id="team-overview")

__init__(client, default_space_id=None, validate_spaces=True)¶

Initialize NamespaceClient with optional space support.

Parameters:

client (BaseClient) – Parent BaseClient 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 (default: True)

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]

AsyncDashboardsClient¶

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

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

Bases: AsyncNamespaceClient

Async client for the Kibana Dashboards HTTP API.

The dashboard data model (the data object) supports:

title (required): human-readable dashboard title.
description: short description of the dashboard.
panels: list of panels and collapsible sections. Each panel has a type (e.g. "markdown", "vis", "image", "discover_session", control panels, SLO/synthetics/APM embeddables), a grid placement (x, y required; w up to 48, defaults 24; h defaults 15) and a type-specific config (either inline “by value” or ref_id “by reference”). Sections are objects with a title, collapsed flag and nested panels.
options: display/behavior settings (auto_apply_filters, hide_panel_borders, hide_panel_titles, sync_colors, sync_cursor, sync_tooltips, use_margins).
filters: filters applied across all panels (simple condition filters, DSL filters, group filters or spatial filters).
query: a search query {"expression": ..., "language": "kql" | "lucene"} applied to the dashboard.
time_range: {"from": ..., "to": ..., "mode": "absolute" | "relative"} accepting date math (e.g. now-7d) or ISO 8601 timestamps.
refresh_interval: {"pause": bool, "value": ms} auto-refresh setting.
tags: list of tag IDs associated with the dashboard.
pinned_panels: control panels and their state in the control group.
access_control: {"access_mode": "default" | "write_restricted"} edit-access setting. Accepted only at creation time (create()); PUT rejects it.
project_routing: cross-project search routing behavior.

Dashboards are space-scoped: every method accepts space_id to target a specific Kibana space (None targets the default space or the client’s default space).

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a dashboard with a markdown panel
>>> dashboard = await client.dashboards.create(
...     title="Team Overview",
...     panels=[
...         {
...             "type": "markdown",
...             "grid": {"x": 0, "y": 0, "w": 24, "h": 15},
...             "config": {"content": "# Welcome", "settings": {}},
...         }
...     ],
... )
>>> dashboard_id = dashboard.body["id"]
>>>
>>> # Search dashboards
>>> results = await client.dashboards.get_all(query="Team*")
>>> for item in results.body["dashboards"]:
...     print(item["id"], item["data"]["title"])

Usage

The AsyncDashboardsClient provides the same methods as DashboardsClient 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:
        # Create a dashboard (async)
        created = await client.dashboards.create(
            title="Async Dashboard",
            panels=[
                {
                    "type": "markdown",
                    "grid": {"x": 0, "y": 0, "w": 24, "h": 15},
                    "config": {"content": "# Hello", "settings": {}},
                }
            ],
        )

        # Search dashboards (async)
        results = await client.dashboards.get_all(query="Async*")

        # Delete (async)
        await client.dashboards.delete(id=created.body["id"])

asyncio.run(main())

Concurrent Operations

Provision multiple dashboards concurrently:

import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        dashboards = await asyncio.gather(
            client.dashboards.create(title="Dashboard 1"),
            client.dashboards.create(title="Dashboard 2"),
            client.dashboards.create(title="Dashboard 3"),
        )
        print(f"Created {len(dashboards)} dashboards")

asyncio.run(main())

async get_all(*, page=None, per_page=None, query=None, tags=None, excluded_tags=None, space_id=None, validate_spaces=None)[source]¶

Search dashboards.

Parameters:

page (int | None) – The page of results to return. Defaults to 1.
per_page (int | None) – The number of results to return per page. Defaults to 20.
query (str | None) – Filters results by title and description using Elasticsearch simple_query_string syntax (e.g. "sales*"). Multi-word terms are OR-ed by default.
tags (list[str] | None) – Tag IDs to include. When multiple are specified, dashboards matching any of the tag IDs are included (max 100).
excluded_tags (list[str] | None) – Tag IDs to exclude. When multiple are specified, dashboards matching any of the tag IDs are excluded (max 100).
space_id (str | None) – Optional space ID to search dashboards in. None targets the default space (or the client’s default space).
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body contains dashboards (a list of {"id", "data", "meta"} envelopes) plus page and total pagination fields.

Raises:

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

Return type:

ObjectApiResponse[Any]

Example

>>> results = await client.dashboards.get_all(
...     query="sales*",
...     tags=["tag-id-1"],
...     per_page=10,
...     page=1,
... )
>>> print(results.body["total"])
>>> for item in results.body["dashboards"]:
...     print(item["id"], item["data"]["title"])

async create(*, title, description=None, panels=None, options=None, filters=None, query=None, time_range=None, refresh_interval=None, tags=None, pinned_panels=None, access_control=None, project_routing=None, space_id=None, validate_spaces=None)[source]¶

Create a dashboard.

Parameters:

title (str) – A human-readable title for the dashboard (required).
description (str | None) – A short description of the dashboard.
panels (list[dict[str, Any]] | None) – Panels and sections. Each panel is a dict with type (e.g. "markdown", "vis", "image"), grid ({"x", "y"} required, optional "w" <= 48 and "h") and a type-specific config (inline config or {"ref_id": ...} for library items). A section is a dict with title, collapsed and nested panels.
options (dict[str, Any] | None) – Display and behavior settings, e.g. {"hide_panel_titles": True, "use_margins": False}. Unspecified keys keep their server defaults.
filters (list[dict[str, Any]] | None) – Filters applied across all panels, including pinned panels (condition, DSL, group or spatial filters).
query (dict[str, Any] | None) – Search query, e.g. {"expression": "status:active", "language": "kql"} (language is "kql" or "lucene").
time_range (dict[str, Any] | None) – Time range, e.g. {"from": "now-7d", "to": "now", "mode": "relative"}. from/to accept date math or ISO 8601 timestamps.
refresh_interval (dict[str, Any] | None) – Auto-refresh setting {"pause": bool, "value": milliseconds}.
tags (list[str] | None) – Tag IDs to associate with this dashboard (max 100).
pinned_panels (list[dict[str, Any]] | None) – Control panels and their state in the control group.
access_control (dict[str, Any] | None) – Access control settings, e.g. {"access_mode": "write_restricted"} to prevent edits by users without explicit write permission. Only settable at creation time — PUT /api/dashboards/{id} (update()) rejects this field. Requires an identifiable user profile: under plain basic auth the server responds 400 (“Kibana could not determine the user profile ID for the caller”).
project_routing (str | None) – Cross-project search routing behavior for the dashboard.
space_id (str | None) – Optional space ID to create the dashboard in.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body is an {"id", "data", "meta"} envelope for the created dashboard.

Raises:

ValueError – If title is missing.
BadRequestError – If the dashboard data fails schema validation (including passing an id field via panels etc.).
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> dashboard = await client.dashboards.create(
...     title="Service health",
...     description="Ops overview",
...     tags=["ops-tag-id"],
...     time_range={"from": "now-24h", "to": "now"},
...     panels=[
...         {
...             "type": "markdown",
...             "grid": {"x": 0, "y": 0, "w": 48, "h": 6},
...             "config": {
...                 "content": "## Runbook links",
...                 "settings": {"open_links_in_new_tab": True},
...             },
...         }
...     ],
... )
>>> print(dashboard.body["id"])

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

Get a dashboard by ID.

Technical preview in 9.4. Retrieves the full dashboard, including its complete panel layout.

Parameters:

id (str) – The dashboard ID to retrieve.
space_id (str | None) – Optional space ID to get the dashboard from.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body is an {"id", "data", "meta"} envelope.

Raises:

ValueError – If id is missing.
NotFoundError – If the dashboard does not exist.
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> dashboard = await client.dashboards.get(id="my-dashboard")
>>> print(dashboard.body["data"]["title"])
>>> for panel in dashboard.body["data"]["panels"]:
...     print(panel["type"], panel["grid"])

async update(*, id, title, description=None, panels=None, options=None, filters=None, query=None, time_range=None, refresh_interval=None, tags=None, pinned_panels=None, project_routing=None, space_id=None, validate_spaces=None)[source]¶

Update (upsert) a dashboard by ID.

Note that the provided data replaces the stored dashboard data — fields omitted from the call revert to their defaults rather than being preserved.

Unlike create(), this endpoint does not accept an access_control field — access control can only be set at creation time, and the server rejects it in a PUT body with a 400 error.

Parameters:

id (str) – The dashboard ID to update or create.
title (str) – A human-readable title for the dashboard (required).
description (str | None) – A short description of the dashboard.
panels (list[dict[str, Any]] | None) – Panels and sections. Each panel is a dict with type (e.g. "markdown", "vis", "image"), grid ({"x", "y"} required, optional "w" <= 48 and "h") and a type-specific config (inline config or {"ref_id": ...} for library items). A section is a dict with title, collapsed and nested panels.
options (dict[str, Any] | None) – Display and behavior settings, e.g. {"hide_panel_titles": True, "use_margins": False}.
filters (list[dict[str, Any]] | None) – Filters applied across all panels, including pinned panels (condition, DSL, group or spatial filters).
query (dict[str, Any] | None) – Search query, e.g. {"expression": "status:active", "language": "kql"} (language is "kql" or "lucene").
time_range (dict[str, Any] | None) – Time range, e.g. {"from": "now-7d", "to": "now", "mode": "relative"}. from/to accept date math or ISO 8601 timestamps.
refresh_interval (dict[str, Any] | None) – Auto-refresh setting {"pause": bool, "value": milliseconds}.
tags (list[str] | None) – Tag IDs to associate with this dashboard (max 100).
pinned_panels (list[dict[str, Any]] | None) – Control panels and their state in the control group.
project_routing (str | None) – Cross-project search routing behavior for the dashboard.
space_id (str | None) – Optional space ID where the dashboard lives.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse whose body is an {"id", "data", "meta"} envelope for the updated or newly created dashboard.

Raises:

ValueError – If id or title is missing.
BadRequestError – If the dashboard data fails schema validation.
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> # Create a dashboard with a custom ID (upsert)
>>> dashboard = await client.dashboards.update(
...     id="team-overview",
...     title="Team Overview",
... )
>>>
>>> # Replace its content later
>>> dashboard = await client.dashboards.update(
...     id="team-overview",
...     title="Team Overview v2",
...     tags=["team-tag-id"],
... )

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

Delete a dashboard by ID.

Technical preview in 9.4. Permanently deletes the dashboard. The server responds 204 with an empty body on success.

Parameters:

id (str) – The dashboard ID to delete.
space_id (str | None) – Optional space ID to delete the dashboard from.
validate_spaces (bool | None) – Override space-existence validation for this call.

Returns:

ObjectApiResponse, empty for successful deletion (HTTP 204).

Raises:

ValueError – If id is missing.
NotFoundError – If the dashboard does not exist.
AuthenticationException – If authentication fails.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.dashboards.delete(id="team-overview")

__init__(client, default_space_id=None, validate_spaces=True)¶

Initialize AsyncNamespaceClient with optional space support.

Parameters:

client (AsyncBaseClient) – Parent AsyncBaseClient 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 (default: True)

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]