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)

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

Option 2: Direct URL with API Key

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

Option 3: Basic Authentication

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 :

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)

export KIBANA_INSECURE="true"

Basic Workflow

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 .

{ "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

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

Update Dashboard

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:

{ "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

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

{ "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.

{ "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' } .

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

ES|QL Column Reference Pattern:

{ "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:

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

Examples

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

Metric (dataView):

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

Metric (ES|QL):

{ "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):

{ "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):

{ "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) :

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 :

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() or 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