Kibana Dashboards

Kibana Dashboards and Lens Visualizations

Create, update, and delete Kibana dashboards and standalone Lens visualizations using the Kibana 9.4+ Dashboards and Visualizations APIs. Produce minimal, diffable JSON bodies; prefer inline panel definitions over library references; and choose the correct dataset type (data view vs ES|QL) before writing metrics or chart layers.

<!-- begin-partial: preamble -->

Environment Configuration

This skill executes Elasticsearch operations through the elastic CLI. If the elastic CLI is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., GET /, GET /_cat/indices, GET /{index}/_mapping, GET /{index}/_settings/index.mode, POST /_query). The Operations table at the end of this document maps each shorthand to the equivalent elastic CLI command — always use the CLI rather than calling the HTTP API directly.

<!-- end-partial: preamble -->

Prerequisites

Version requirement: Kibana 9.4+ (Dashboards and Visualizations APIs).

ES|QL placement:

• Standalone library charts: PUT kbn:/api/visualizations/{id} with data_source.type: "esql".
• ES|QL panels embedded in a dashboard: inline vis panel config with data_source.type: "esql" via PUT kbn:/api/dashboards/{id}.
• Do not use data_source.type: "data_view_reference" or index-pattern aggregations when the user explicitly requests ES|QL — the persisted Lens state must use a text-based ES|QL datasource (textBased / esql), not a data-view count operation.

Process

1. Verify Kibana connectivity. Call GET kbn:/api/status. If the call fails, stop and surface the error — do not guess endpoints or credentials. Read version.number to confirm the cluster meets the 9.4+ requirement.

2. Classify the task. Decide whether the user needs a dashboard (collection of panels, optional time range), a standalone Lens visualization (library item referenced by id or used alone), or both. Determine whether a deterministic saved-object id was supplied — when given, use upsert (PUT) with that id rather than POST (which auto-generates ids).

3. Choose the dataset type before building metrics or layers.

   User intent	Dataset	Metric / axis pattern
   Simple count or aggregation on a saved data view	data_source.type: "data_view_reference" with ref_id	metrics: [{ type: "primary", operation: "count" }] (or other aggregation operations)
   Ad-hoc index pattern	data_source.type: "data_view_spec" with index_pattern and time_field	Same aggregation operation fields
   ES|QL query (explicit or complex logic)	data_source.type: "esql" with query	metrics: [{ type: "primary", column: "<alias>" }] or layer axes { column: "<alias>" } — never operation: "count" on the metric

   Write the aggregation in the ES|QL query (STATS count = COUNT()), then reference the resulting column by name.

4. Build a dashboard body when creating or updating dashboards. The request body is flat — title, panels, and optional time_range at the root. Do not wrap in { data: ... } on write. Required fields:

   • title — exact string the user requested.
   • panels — array; use [] when the user asks for an empty dashboard (do not omit the key or invent panels).
   • time_range — when the user specifies a default time filter, set { "from": "<expr>", "to": "<expr>" } (for example { "from": "now-7d", "to": "now" }). Supplying time_range persists the dashboard time filter on open (equivalent to enabling time restore in the UI).

   Upsert with a deterministic id:

   {
     "title": "Sales Overview",
     "panels": [],
     "time_range": { "from": "now-7d", "to": "now" }
   }

   Call PUT kbn:/api/dashboards/eval-sales-overview with the body above when the user supplies that id.

   Inline ES|QL metric panel example (inside panels):

   {
     "type": "vis",
     "id": "total-requests",
     "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
     "config": {
       "title": "Total Requests",
       "type": "metric",
       "data_source": {
         "type": "esql",
         "query": "FROM logs* | STATS count = COUNT()"
       },
       "metrics": [{ "type": "primary", "column": "count" }]
     }
   }

   Prefer inline config properties over config.ref_id for portable dashboards. Read Dashboard API Reference for panel types, grid layout, and copy workflows.

5. Build a standalone Lens visualization when the user asks for a library chart. Use the Visualizations API. Upsert with PUT kbn:/api/visualizations/{id} when an id is supplied; otherwise POST kbn:/api/visualizations and report the generated id from the response.

   ES|QL metric (total count from logs):

   {
     "type": "metric",
     "title": "Total Requests",
     "data_source": {
       "type": "esql",
       "query": "FROM logs* | STATS count = COUNT()"
     },
     "metrics": [{ "type": "primary", "column": "count" }]
   }

   Call PUT kbn:/api/visualizations/eval-total-requests when that id is required. The API persists a Lens saved object whose datasource state uses ES|QL (textBased / esql), not an index-pattern aggregation.

   Read Lens API Reference and Chart Types Reference for xy, gauge, heatmap, and other chart schemas.

6. Execute and confirm. Perform the write with PUT kbn:/api/dashboards/{id} or PUT kbn:/api/visualizations/{id} (or POST when no id is supplied). Confirm with GET kbn:/api/dashboards/{id} or GET kbn:/api/visualizations/{id}. Report the id and title back to the user — do not claim success without a successful read-back.

7. List, export, or delete when requested. Call GET kbn:/api/dashboards or GET kbn:/api/visualizations to discover existing objects. Call DELETE kbn:/api/dashboards/{id} or DELETE kbn:/api/visualizations/{id} to remove objects. For bulk export or import of saved objects, call POST kbn:/api/saved_objects/_export or POST kbn:/api/saved_objects/_import.