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 '
' | node scripts/kibana-dashboards.js dashboard create - echo ' ' | 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 '
' | node scripts/kibana-dashboards.js lens create - echo ' ' | 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 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