SKILL.md

Kibana Dashboards and Visualizations

Name: kibana-dashboards
Author: elastic

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

ES|QL Visualizations: ES|QL-based visualizations cannot be created via /api/visualizations. They must be created

as inline panels within dashboards using the Dashboard API.

Inline vs Saved Object References: When embedding visualization panels in dashboards, prefer inline definitions

over ref_id 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>

echo '<json>' | node scripts/kibana-dashboards.js dashboard upsert <id> -

# Visualization operations (standalone saved objects)

node scripts/kibana-dashboards.js vis list

node scripts/kibana-dashboards.js vis get <id>

echo '<json>' | node scripts/kibana-dashboards.js vis create -

echo '<json>' | node scripts/kibana-dashboards.js vis update <id> -

node scripts/kibana-dashboards.js vis delete <id>

echo '<json>' | node scripts/kibana-dashboards.js vis upsert <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.

Dashboard with Inline Visualization Panels (Recommended)

Use inline definitions (properties directly in config) for self-contained, portable dashboards:

{

  "title": "My Dashboard",

  "panels": [

    {

      "type": "vis",

      "id": "metric-panel",

      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },

      "config": {

        "title": "",

        "type": "metric",

        "data_source": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },

        "metrics": [{ "type": "primary", "column": "total", "label": "Total Count" }]

      }

    },

    {

      "type": "vis",

      "id": "chart-panel",

      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },

      "config": {

        "title": "Events Over Time",

        "type": "xy",

        "axis": {

          "x": { "scale": "temporal", "domain": { "type": "fit", "rounding": false } }

        },

        "layers": [

          {

            "type": "area",

            "data_source": {

              "type": "esql",

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

            },

            "x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" },

            "y": [{ "column": "count" }]

          }

        ]

      }

    }

  ],

  "time_range": { "from": "now-24h", "to": "now" }

}

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

Large

14-16

Wide time series, tables

Half

Standard

10-12

Primary charts

Quarter

Compact

5-6

KPI metrics

Sixth

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": "vis",

  "id": "unique-panel-id",

  "grid": { "x": 0, "y": 0, "w": 24, "h": 15 },

  "config": { ... }

}

Property

Type

Required

Description

type

string

Yes

Embeddable type (e.g., vis, markdown, map)

id

string

Unique panel ID (auto-generated if omitted)

grid

object

Yes

Position and size (x, y, w, h)

config

object

Yes

Panel-specific configuration

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

tag_cloud

Tag/word cloud

Yes

data_table

Data tables

Yes

region_map

Region/choropleth maps

Yes

pie, treemap, mosaic, waffle

Partition charts

Yes

Note: To create donut charts, use pie with donut_hole set to "s", "m", or "l" (small, medium, large

hole). Use "none" for a solid pie.

Dataset Types

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

and dimensions.

#### Data View Dataset

Use data_view_reference with aggregation operations. Kibana performs the aggregations automatically.

{

  "data_source": {

    "type": "data_view_reference",

    "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247"

  }

}

Available operations: count, average, sum, max, min, unique_count, median, standard_deviation,

percentile, percentile_rank, last_value, date_histogram, terms. See

Chart Types Reference for details.

#### ES|QL Dataset

Use esql with a query string. Reference the output columns using { column: 'column_name' }.

{

  "data_source": {

    "type": "esql",

    "query": "FROM logs | STATS count = COUNT(), avg_bytes = AVG(bytes) BY host"

  }

}

ES|QL Column Reference Pattern:

{ "column": "count" }

Key Difference: With ES|QL, you write the aggregation in the query itself, then reference the resulting columns.

With data view, you specify the aggregation operation and Kibana performs it.

Important: ES|QL visualizations cannot be created via /api/visualizations. They must be created as inline panels

in dashboards via the Dashboard API.

#### Index Dataset

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

{

  "data_source": {

    "type": "data_view_spec",

    "index_pattern": "logs-*",

    "time_field": "@timestamp"

  }

}

Examples

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

Metric (Data View):

{

  "type": "metric",

  "data_source": { "type": "data_view_reference", "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247" },

  "metrics": [{ "type": "primary", "operation": "count", "label": "Total Requests" }]

}

Metric (ES|QL):

{

  "type": "metric",

  "data_source": { "type": "esql", "query": "FROM logs | STATS count = COUNT()" },

  "metrics": [{ "type": "primary", "column": "count", "label": "Total Requests" }]

}

XY Bar Chart (Data View):

{

  "title": "Top Hosts",

  "type": "xy",

  "axis": { "x": { "title": { "visible": false } }, "y": { "anchor": "start", "title": { "visible": false } } },

  "layers": [

    {

      "type": "bar_horizontal",

      "data_source": { "type": "data_view_reference", "ref_id": "90943e30-9a47-11e8-b64d-95841ca0b247" },

      "x": { "operation": "terms", "fields": ["host.keyword"], "limit": 10 },

      "y": [{ "operation": "count" }]

    }

  ]

}

XY Time Series (ES|QL):

{

  "title": "Requests Over Time",

  "type": "xy",

  "axis": {

    "x": { "title": { "visible": false }, "scale": "temporal", "domain": { "type": "fit", "rounding": false } },

    "y": { "anchor": "start", "title": { "visible": false } }

  },

  "layers": [

    {

      "type": "line",

      "data_source": {

        "type": "esql",

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

      },

      "x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" },

      "y": [{ "column": "count" }]

    }

  ]

}

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

long labels. Use axis for axis configuration.

Full Documentation

Dashboard API Reference — Dashboard endpoints and schemas

Visualizations API Reference — Visualization endpoints

Chart Types Reference — Detailed schemas for each chart type

Example Definitions — Ready-to-use definitions

Key Example Files

See assets/ for ready-to-use definitions: demo-dashboard.json, dashboard-with-visualizations.json,

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

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 already exists; delete first or use update

Schema validation error

Ensure column names match query output; use { column: 'name' } for ES|QL

Metric chart structure

Requires metrics array: [{ type: 'primary', ... }]

XY chart fails

Put data_source inside each layer, use axis (singular)

ref_id panels missing

Prefer inline definitions (properties in config) over ref_id

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 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, hide axis titles — Write titles that explain what the chart shows (e.g., "Requests

by Response Code"). A good panel title makes axis titles redundant. Always set axis.x.title.visible: false and

axis.y.title.visible: false.

Choose the right dataset type — Use data_view_reference for simple aggregations, esql for complex queries

Inline definitions — Prefer inline properties in config over config.ref_id for portable dashboards

Test connection first — Run node scripts/kibana-dashboards.js test before creating resources

Get existing examples — Use vis get <id> to see the exact schema for different chart types (the CLI subcommand

is vis)

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

Format numbers with units — Use the format property on metrics and y-axis columns to display proper units

instead of raw numbers. Types: bytes, bits, number, percent, duration, custom. Example:

"format": { "type": "bytes", "decimals": 0 }. See Chart Types Reference for

the full format table.

Schema Differences: Data View vs ES|QL

Aspect

Data View

ES|QL

Dataset

{ type: 'data_view_reference', ref_id: '...' }

{ type: 'esql', query: '...' }

Metric chart

metrics: [{ type: 'primary', operation: 'count' }]

metrics: [{ type: 'primary', column: 'col' }]

XY columns

{ operation: 'terms', fields: ['host'], limit: 10 }

{ column: 'host' }

Static values

{ operation: 'static_value', value: 100 }

Use EVAL in query (see below)

XY data_source

Inside each layer

Tagcloud

tag_by: { operation: 'terms', ... }

tag_by: { column: '...' }

Datatable props

metrics, rows arrays

metrics, rows arrays with { column: '...' }

Key Pattern: ES|QL uses { column: 'column_name' } to reference columns from the query result. The aggregation

happens in the ES|QL query itself. Use data_source for all data source configuration.

Data source types: Use data_view_reference (with ref_id) for saved data views, data_view_spec (with

index_pattern) for ad-hoc index patterns, and esql for ES|QL queries.

ES|QL: Time Bucketing

Use BUCKET(@timestamp, n, ?_tstart, ?_tend) for time series charts. The numeric argument is the target number of

buckets. Kibana injects ?_tstart/?_tend automatically. Do not reassign the result — use the full expression

BUCKET(@timestamp, 75, ?_tstart, ?_tend) as both the BY clause and the column reference. Set "label" to provide

a friendly display name:

"x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" }

Important: To get a proper multilevel time axis (e.g., "9th / April 2026 / 10th") instead of raw timestamp labels,

you must set "scale": "temporal" on the x-axis:

"axis": {

  "x": { "scale": "temporal", "domain": { "type": "fit", "rounding": false } }

}

Without "scale": "temporal", Kibana treats the bucket column as categorical text and renders unsorted, verbose

timestamp strings.

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

Note: BUCKET(@timestamp, n, ?_tstart, ?_tend) requires a WHERE clause with ?_tstart/?_tend bounds (Kibana

injects these). Alternatively, use BUCKET(@timestamp, 1 hour) with a fixed duration — this does not require

parameters but won't auto-scale.

ES|QL: Extracting Date Parts

Use DATE_EXTRACT(part, date) with ES|QL part names (not SQL keywords). The part string must be double-quoted. Common

parts: "hour_of_day", "day_of_week", "day_of_month", "month_of_year", "year", "day_of_year".

FROM logs | STATS count = COUNT() BY hour = DATE_EXTRACT("hour_of_day", @timestamp), day = DATE_EXTRACT("day_of_week", @timestamp)

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

kibana-dashboards