Kibana Dashboards and Visualizations

Overview

The Kibana dashboards and visualizations APIs provide a declarative, Git-friendly format for defining dashboards and visualizations. Definitions are minimal, diffable, and suitable for version control and LLM-assisted generation.

Key Benefits:

Minimal payloads (no implementation details or derivable properties)
Easy to diff in Git
Consistent patterns for GitOps workflows
Designed for LLM one-shot generation
Robust validation via OpenAPI spec

Version Requirement: Kibana 9.4+ (SNAPSHOT)

Important Caveats

Inline vs Saved Object References: When embedding Lens panels in dashboards, prefer inline
attributes
definitions over
savedObjectId
references. Inline definitions are more reliable and self-contained.

Quick Start

Environment Configuration

Kibana connection is configured via environment variables. Run

node scripts/kibana-dashboards.js test

to verify the connection. If the test fails, suggest these setup options to the user, then stop. Do not try to explore further until a successful connection test.

Option 1: Elastic Cloud (recommended for production)

bash

export KIBANA_CLOUD_ID="deployment-name:base64encodedcloudid"
export KIBANA_API_KEY="base64encodedapikey"

Option 2: Direct URL with API Key

bash

export KIBANA_URL="https://your-kibana:5601"
export KIBANA_API_KEY="base64encodedapikey"

Option 3: Basic Authentication

bash

export KIBANA_URL="https://your-kibana:5601"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="changeme"

Option 4: Local Development with start-local

Use start-local to spin up Elasticsearch/Kibana locally, then source the generated

.env

bash

curl -fsSL https://elastic.co/start-local | sh
source elastic-start-local/.env
export KIBANA_URL="$KB_LOCAL_URL"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="$ES_LOCAL_PASSWORD"

Then run

node scripts/kibana-dashboards.js test

to verify the connection.

Optional: Skip TLS verification (development only)

bash

export KIBANA_INSECURE="true"

Basic Workflow

bash

# Test connection and API availability
node scripts/kibana-dashboards.js test

# Dashboard operations
node scripts/kibana-dashboards.js dashboard get <id>
echo '<json>' | node scripts/kibana-dashboards.js dashboard create -
echo '<json>' | node scripts/kibana-dashboards.js dashboard update <id> -
node scripts/kibana-dashboards.js dashboard delete <id>

# Lens visualization operations
node scripts/kibana-dashboards.js lens list
node scripts/kibana-dashboards.js lens get <id>
echo '<json>' | node scripts/kibana-dashboards.js lens create -
echo '<json>' | node scripts/kibana-dashboards.js lens update <id> -
node scripts/kibana-dashboards.js lens delete <id>

Dashboards API

Dashboard Definition Structure

The API expects a flat request body with

title

and

panels

at the root level. The response wraps these in a

data

envelope alongside

id

meta

, and

spaces

json

{
  "title": "My Dashboard",
  "panels": [ ... ],
  "time_range": {
    "from": "now-24h",
    "to": "now"
  }
}

Note: Dashboard IDs are auto-generated by the API. The script also accepts the legacy wrapped format
{ id?, data: { title, panels }, spaces? }
and unwraps it automatically.

Create Dashboard

bash

echo '{
  "title": "Sales Dashboard",
  "panels": [],
  "time_range": { "from": "now-7d", "to": "now" }
}' | node scripts/kibana-dashboards.js dashboard create -

Update Dashboard

bash

echo '{
  "title": "Updated Dashboard Title",
  "panels": [ ... ]
}' | node scripts/kibana-dashboards.js dashboard update my-dashboard-id -

Dashboard with Inline Lens Panels (Recommended)

Use inline

attributes

for self-contained, portable dashboards:

json

{
  "title": "My Dashboard",
  "panels": [
    {
      "type": "lens",
      "uid": "metric-panel",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
      "config": {
        "attributes": {
          "title": "",
          "type": "metric",
          "dataset": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },
          "metrics": [{ "type": "primary", "operation": "value", "column": "total", "label": "Total Count" }]
        }
      }
    },
    {
      "type": "lens",
      "uid": "chart-panel",
      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },
      "config": {
        "attributes": {
          "title": "Events Over Time",
          "type": "xy",
          "layers": [
            {
              "type": "area",
              "dataset": {
                "type": "esql",
                "query": "FROM logs | STATS count = COUNT(*) BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "x": { "operation": "value", "column": "bucket" },
              "y": [{ "operation": "value", "column": "count" }]
            }
          ]
        }
      }
    }
  ],
  "time_range": { "from": "now-24h", "to": "now" }
}

Copy Dashboard Between Spaces/Clusters

bash

# 1. Get dashboard from source
node scripts/kibana-dashboards.js dashboard get source-dashboard > dashboard.json

# 2. Edit dashboard.json to change id and/or spaces

# 3. Create on destination
node scripts/kibana-dashboards.js dashboard create dashboard.json

Dashboard Grid System

Dashboards use a 48-column, infinite-row grid. On 16:9 screens, approximately 20-24 rows are visible without scrolling. Design for density—place primary KPIs and key trends above the fold.

Width	Columns	Height	Rows	Use Case
Full	48	Large	14-16	Wide time series, tables
Half	24	Standard	10-12	Primary charts
Quarter	12	Compact	5-6	KPI metrics
Sixth	8	Minimal	4-5	Dense metric rows

Target: 8-12 panels above the fold. Use descriptive panel titles on the charts themselves instead of adding markdown headers.

Grid Packing Rules:

Eliminate Dead Space: Always calculate the bottom edge (
```
y + h
```
) of every panel. When starting a new row or placing a panel below another, its
```
y
```
coordinate must exactly match the
```
y + h
```
of the panel immediately above it.
Align Row Heights: If multiple panels are placed side-by-side in a row (e.g., sharing the same
```
y
```
coordinate), they should generally have the exact same height (
```
h
```
). If they do not, you must fill the resulting empty vertical space before placing the next full-width panel.

Panel Schema

json

{
  "type": "lens",
  "uid": "unique-panel-id",
  "grid": { "x": 0, "y": 0, "w": 24, "h": 15 },
  "config": { ... }
}

Property	Type	Required	Description
`type`	string	Yes	Embeddable type (e.g., `lens` , `visualization` , `map` )
`uid`	string	No	Unique panel ID (auto-generated if omitted)
`grid`	object	Yes	Position and size ( `x` , `y` , `w` , `h` )
`config`	object	Yes	Panel-specific configuration

Lens Visualizations API

Supported Chart Types

Type	Description	ES\|QL Support
`metric`	Single metric value display	Yes
`xy`	Line, area, bar charts	Yes
`gauge`	Gauge visualizations	Yes
`heatmap`	Heatmap charts	Yes
`tagcloud`	Tag/word cloud	Yes
`datatable`	Data tables	Yes
`region_map`	Region/choropleth maps	Yes
`pie` , `donut` , `treemap` , `mosaic` , `waffle`	Partition charts	Yes

Dataset Types

There are three dataset types supported in the Lens API. Each uses different patterns for specifying metrics and dimensions.

Data View Dataset

Use

dataView

with aggregation operations. Kibana performs the aggregations automatically.

json

{
  "dataset": {
    "type": "dataView",
    "id": "90943e30-9a47-11e8-b64d-95841ca0b247"
  }
}

Available Aggregation Operations (for dataView):

Operation	Description	Requires Field
`count`	Document count	No
`average`	Average value	Yes
`sum`	Sum of values	Yes
`max`	Maximum value	Yes
`min`	Minimum value	Yes
`unique_count`	Cardinality	Yes
`median`	Median value	Yes
`standard_deviation`	Standard deviation	Yes
`percentile`	Percentile (with `percentile` param)	Yes
`percentile_rank`	Percentile rank (with `rank` param)	Yes
`last_value`	Last value (with `sort_by` field)	Yes
`date_histogram`	Time buckets (for x-axis)	Yes
`terms`	Top values (for x-axis/breakdown)	Yes

ES|QL Dataset

Use

esql

with a query string. Reference the output columns using

{ operation: 'value', column: 'column_name' }

json

{
  "dataset": {
    "type": "esql",
    "query": "FROM logs | STATS count = COUNT(), avg_bytes = AVG(bytes) BY host"
  }
}

ES|QL Column Reference Pattern:

json

{
  "operation": "value",
  "column": "count"
}

Key Difference: With ES|QL, you write the aggregation in the query itself, then reference the resulting columns. With dataView, you specify the aggregation operation and Kibana performs it.

Index Dataset

Use

index

for ad-hoc index patterns without a saved data view:

json

{
  "dataset": {
    "type": "index",
    "index": "logs-*",
    "time_field": "@timestamp"
  }
}

Examples

For detailed schemas and all chart type options, see Chart Types Reference.

Metric (dataView):

json

{
  "type": "metric",
  "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
  "metrics": [{ "type": "primary", "operation": "count", "label": "Total Requests" }]
}

Metric (ES|QL):

json

{
  "type": "metric",
  "dataset": { "type": "esql", "query": "FROM logs | STATS count = COUNT()" },
  "metrics": [{ "type": "primary", "operation": "value", "column": "count", "label": "Total Requests" }]
}

XY Bar Chart (dataView):

json

{
  "title": "Top Hosts",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "bar_horizontal",
      "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
      "x": { "operation": "terms", "fields": ["host.keyword"], "size": 10 },
      "y": [{ "operation": "count" }]
    }
  ]
}

XY Time Series (ES|QL):

json

{
  "title": "Requests Over Time",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "line",
      "dataset": {
        "type": "esql",
        "query": "FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
      },
      "x": { "operation": "value", "column": "bucket" },
      "y": [{ "operation": "value", "column": "count" }]
    }
  ]
}

Tip: Always hide axis titles when the panel title is descriptive. Use
bar_horizontal
for categorical data with long labels.

Full Documentation

Dashboard API Reference — Dashboard endpoints and schemas
Lens API Reference — Lens visualization endpoints
Chart Types Reference — Detailed schemas for each chart type
Example Definitions — Ready-to-use definitions

Key Example Files

```
assets/demo-dashboard.json
```
— Complete dashboard with inline Lens panels (dataView format)
```
assets/dashboard-with-lens.json
```
— Dashboard with ES|QL format (for future reference)
```
assets/metric-esql.json
```
— Standalone metric visualization
```
assets/bar-chart-esql.json
```
— Bar chart example
```
assets/line-chart-timeseries.json
```
— Time series line chart

Common Issues

Error	Solution
"401 Unauthorized"	Check KIBANA_USERNAME/PASSWORD or KIBANA_API_KEY
"404 Not Found"	Verify dashboard/visualization ID exists
"409 Conflict"	Dashboard/viz with that ID already exists; delete first or use update
"id not allowed in PUT"	Remove `id` and `spaces` from update body
Schema validation error	For ES\|QL: ensure column names match query output; use `{ operation: 'value', column: 'name' }`
ES\|QL missing `operation`	ES\|QL requires `{ operation: 'value', column: 'col' }` , not just `{ column: 'col' }`
Metric uses `metric` not `metrics`	Metric chart requires `metrics` (plural) array: `[{ type: 'primary', operation: '...' }]`
Tagcloud uses `tag` not `tag_by`	Tagcloud requires `tag_by` , not `tag`
Datatable uses `columns`	ES\|QL datatable requires `metrics` + `rows` arrays, not `columns`
XY chart fails	Put `dataset` inside each layer (for both dataView and ES\|QL)
Heatmap property names	Use `xAxis` , `yAxis` , `metric` (not `x` , `y` , `value` )
savedObjectId panels missing	Prefer inline `attributes` definitions over savedObjectId

Guidelines

Design for density — Operational dashboards must show 8-12 panels above the fold (within the first 24 rows). Use compact panel heights: metrics MUST be
```
h=4
```
to
```
h=6
```
, and charts MUST be
```
h=8
```
to
```
h=12
```
.
Never use Markdown for titles/headers — Do NOT add
```
DASHBOARD_MARKDOWN
```
panels to act as dashboard titles or section dividers. This wastes critical vertical space. Use descriptive panel titles on the charts themselves.
Prioritize above the fold — Primary KPIs and key trends must be placed at
```
y=0
```
. Deep-dives and data tables should be placed below the charts.
Use descriptive chart titles — Write titles that explain what the chart shows (e.g., "Revenue by Product Category"). Hide axis labels with
```
axis.x.title.visible: false
```
to reduce clutter
Choose the right dataset type — Use
```
dataView
```
for simple aggregations,
```
esql
```
for complex queries with joins, transformations, or custom logic
Inline Lens definitions — Prefer
```
config.attributes
```
over
```
config.savedObjectId
```
for portable dashboards
Test connection first — Run
```
node scripts/kibana-dashboards.js test
```
before creating resources
Get existing examples — Use
```
lens get <id>
```
to see the exact schema for different chart types
Avoid redundant metric labels — For ES|QL metrics, avoid using both a panel title and an inner metric label, as it wastes space. Set the panel
```
title
```
to
```
""
```
and configure the human-readable label by aliasing the ES|QL column name using backticks (e.g.,
```
STATS `Total Requests` = COUNT()
```
and
```
"column": "Total Requests"
```
).

Schema Differences: dataView vs ES|QL

Aspect	dataView	ES\|QL
Dataset	`{ type: 'dataView', id: '...' }`	`{ type: 'esql', query: '...' }`
Metric chart	`metrics: [{ type: 'primary', operation: 'count' }]`	`metrics: [{ type: 'primary', operation: 'value', column: 'col' }]`
XY columns	`{ operation: 'terms', fields: ['host'], size: 10 }`	`{ operation: 'value', column: 'host' }`
Static values	`{ operation: 'static_value', value: 100 }`	Use `EVAL` in query (see below)
XY dataset	Inside each layer	Inside each layer
Tagcloud	`tag_by: { operation: 'terms', ... }`	`tag_by: { operation: 'value', column: '...' }`
Datatable props	`metrics` , `rows` arrays	`metrics` , `rows` arrays with `{ operation: 'value', column: '...' }`

Key Pattern: ES|QL always uses
{ operation: 'value', column: 'column_name' }
to reference columns from the query result. The aggregation happens in the ES|QL query itself.

ES|QL: Time Bucketing

For time series charts, use the

BUCKET

function to create "auto" buckets that automatically scale with the time range. Always use

BUCKET(@timestamp, 75, ?_tstart, ?_tend)

instead of hardcoded intervals like

DATE_TRUNC(1 hour, @timestamp)

esql

FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)

ES|QL: Creating Static/Constant Values

ES|QL does not support

static_value

operations. Instead, create constant columns using

EVAL

esql

FROM logs | STATS count = COUNT() | EVAL max_value = 20000, goal = 15000

Then reference with

{ "operation": "value", "column": "max_value" }

. For dynamic reference values, use aggregation functions like

PERCENTILE()

MAX()

in the query.

Design Principles

The APIs follow these principles:

Minimal definitions — Only required properties; defaults are injected
No implementation details — No internal state or machine IDs
Flat structure — Shallow nesting for easy diffing
Semantic names — Clear, readable property names
Git-friendly — Easy to track changes in version control
LLM-optimized — Compact format suitable for one-shot generation

kibana-dashboards

NPX Install

Tags

SKILL.md Content

Kibana Dashboards and Visualizations

Overview

Important Caveats

Quick Start

Environment Configuration

Option 1: Elastic Cloud (recommended for production)

Option 2: Direct URL with API Key

Option 3: Basic Authentication

Option 4: Local Development with start-local

Optional: Skip TLS verification (development only)

Basic Workflow

Dashboards API

Dashboard Definition Structure

Create Dashboard

Update Dashboard

Dashboard with Inline Lens Panels (Recommended)

Copy Dashboard Between Spaces/Clusters

Dashboard Grid System

Panel Schema

Lens Visualizations API

Supported Chart Types

Dataset Types

Data View Dataset

ES|QL Dataset

Index Dataset

Examples

Full Documentation

Key Example Files

Common Issues

Guidelines

Schema Differences: dataView vs ES|QL

ES|QL: Time Bucketing

ES|QL: Creating Static/Constant Values

Design Principles