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](#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.

1. 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).

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

1. 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](references/dashboard-api-reference.md) for panel types, grid layout, and copy workflows.

1. 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](references/lens-api-reference.md) and

[Chart Types Reference](references/chart-types-reference.md) for xy, gauge, heatmap, and other chart schemas.

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

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

Dashboard grid

Dashboards use a 48-column grid. On 16:9 screens, roughly 20–24 rows fit above the fold — target 8–12 panels

in that band.

| Width | Columns | Height (rows) | Use case |

| ------- | ------- | ------------- | ------------------------ |

| Full | 48 | 14–16 | Wide time series, tables |

| Half | 24 | 10–12 | Primary charts |

| Quarter | 12 | 5–6 | KPI metrics |

| Sixth | 8 | 4–5 | Dense metric rows |

Grid packing: When stacking rows, set the next panel's y to the previous panel's y + h. Panels sharing a row

should use the same h. Do not add markdown panels as dashboard titles — use descriptive chart titles instead.

ES|QL patterns

Time series bucket (dashboard time picker injects ?_tstart / ?_tend):

FROM logs*
| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart
| STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)

Set "scale": "temporal" on the x-axis for time-series xy charts. See

[Chart Types Reference](references/chart-types-reference.md) for axis and layer details.

Static reference values — use EVAL in the query, then reference the column:

FROM logs* | STATS count = COUNT() | EVAL goal = 15000

Examples

Example JSON definitions live under [assets/](assets/): demo-dashboard.json, dashboard-with-visualizations.json,

metric-esql.json, bar-chart-esql.json, line-chart-timeseries.json.

Guidelines

1. Match the user's id and title exactly when supplied — do not substitute auto-generated ids.
2. Honor empty panels — when the user asks for panels: [], send an empty array; do not add placeholder panels.
3. ES|QL when requested — use data_source.type: "esql" and column references; never satisfy an ES|QL request with

operation: "count" on a data view.

1. Minimal payloads — omit derivable defaults; let the API inject styling and metadata.
2. Confirm writes — always read back with GET after create or update.
3. Read references before complex charts — metric and xy schemas differ between data view and ES|QL; consult

[Chart Types Reference](references/chart-types-reference.md) before generating partition or table charts.

Common issues

| Error | Likely cause | Fix |

| ----------------------------------- | --------------------------- | ---------------------------------------------------------------------------- |

| 404 on GET after PUT | Wrong id or space | Confirm id and retry GET kbn:/api/dashboards/{id} |

| 400 validation | ES\|QL column mismatch | Align metrics[].column / layer column with STATS aliases in the query |

| ES\|QL panel saved as data view | Wrong dataset type | Use data_source.type: "esql", not data_view_reference |

| Empty dashboard missing time filter | Omitted time_range | Include { "from": "now-7d", "to": "now" } when a default range is required |

| XY chart failure | Missing layer data_source | Put data_source inside each layer, not only at the root |

Operations

As of CLI v0.3.0 the Dashboards and Visualizations APIs have dedicated elastic kb dashboards and

elastic kb visualizations commands for listing, reading, updating, and deleting objects by id. The create-*-redirect

commands do not accept a request body yet, so to write a new object supply an id and use the update-*-redirect (PUT)

command, which carries the JSON body via --input-file. To author several objects at once, build a saved-object NDJSON

and import it with post-saved-objects-import (read it back with post-saved-objects-export).

| HTTP API (shorthand) | elastic CLI command |

| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| GET kbn:/api/status | elastic kb system get-status |

| POST kbn:/api/saved_objects/_import | elastic kb saved-objects post-saved-objects-import --file '<path.ndjson>' --overwrite |

| POST kbn:/api/saved_objects/_export | elastic kb saved-objects post-saved-objects-export --objects '[{"type":"<type>","id":"<id>"}]' |

| GET kbn:/api/dashboards | elastic kb dashboards get-dashboards-redirect |

| GET kbn:/api/dashboards/{id} | elastic kb dashboards get-dashboard-redirect --id '<id>' |

| PUT kbn:/api/dashboards/{id} | elastic kb dashboards update-dashboard-redirect --id '<id>' --input-file '<path.json>' |

| DELETE kbn:/api/dashboards/{id} | elastic kb dashboards delete-dashboard-redirect --id '<id>' |

| POST kbn:/api/dashboards (no id) | create-dashboard-redirect takes no body yet — supply an id and use update-dashboard-redirect, or author via post-saved-objects-import (type dashboard) |

| GET kbn:/api/visualizations | elastic kb visualizations get-visualizations-redirect |

| GET kbn:/api/visualizations/{id} | elastic kb visualizations get-visualization-redirect --id '<id>' |

| PUT kbn:/api/visualizations/{id} | elastic kb visualizations update-visualization-redirect --id '<id>' --input-file '<path.json>' |

| DELETE kbn:/api/visualizations/{id} | elastic kb visualizations delete-visualization-redirect --id '<id>' |

| POST kbn:/api/visualizations (no id) | create-visualization-redirect takes no body yet — supply an id and use update-visualization-redirect, or author via post-saved-objects-import (type lens) |