Dashboards

A dashboard is a collection of panels arranged on a grid. Each panel can contain a visualization, a Discover session, an image, markdown text, or an interactive filter control. Use this API to create and manage dashboards programmatically.

• Use this API to define a complete, self-contained dashboard in a single payload, including inline visualizations (both data view and ES|QL based), controls, and filters.
• Use the Visualizations API to create reusable charts saved to your visualization library. You can then embed them in dashboards as linked panels using their ID.

¹ This version introduces breaking changes. Refer to the Kibana release notes.

² On July 13, 2026, a new version of this API released on Elastic Cloud Serverless and introduced breaking changes. Refer to the Elastic Cloud Serverless release notes.

Before you begin:

• Authentication: Refer to Authentication in the Kibana API documentation.
• CSRF protection: Write operations (POST, PUT, DELETE) require the kbn-xsrf: true header.
• Spaces: If you use non-default Kibana spaces, prepend s/{space_id}/ to the path.

Create your first dashboard right now. The following example creates a dashboard with an ES|QL line chart showing log entries over time. You can run it as-is once you have the Kibana sample logs dataset installed:

curl -X POST "${KIBANA_URL}/api/dashboards" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first API dashboard",
    "panels": [
      {
        "grid": {
          "x": 0,
          "y": 0,
          "w": 24,
          "h": 10
        },
        "type": "vis",
        "config": {
          "type": "xy",
          "title": "Total log entries over time",
          "layers": [
            {
              "type": "line",
              "data_source": {
                "type": "esql",
                "query": "FROM kibana_sample_data_logs | STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "x": {
                "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "y": [
                {
                  "column": "count"
                }
              ]
            }
          ],
          "axis": {
            "x": {
              "title": {
                "visible": false
              }
            }
          }
        }
      }
    ]
  }'
		

All examples on this page use Kibana sample datasets (kibana_sample_data_logs, kibana_sample_data_ecommerce, kibana_sample_data_flights). To use your own data, replace the FROM pattern and field references.

A dashboard is structured as follows:

• title (required): the display name of the dashboard.

• panels: array of items placed on a 48-column grid. Each item has a type, a grid position (x, y, w, h), and a config. Two item shapes are supported:

  • Panel: any content type, including visualizations, Discover sessions, images, markdown, and filter controls. The type field determines the panel's content and the structure of its config.
  • Section: a collapsible group of panels. Use sections to organize a large dashboard into logical groups. A section has a grid.y position and its own nested panels array.

  The grid is 48 columns wide. Use w: 48 for a full-width panel, w: 24 for half-width, and so on. Height (h) and vertical position (y) are in grid rows with no fixed maximum.

• pinned_panels: filter controls pinned at the top of the dashboard that apply to all panels. Filter controls placed in panels apply only to panels in the same section.

• filters, query, time_range: filter the data displayed across all panels.

The type field in each panel determines what it contains and the structure of its config:

Additional panel types for observability use cases:

Additional panel types for machine learning use cases:

You can specify a panel inline so it exists only in that dashboard, or reference a panel already saved to the library and link it from multiple dashboards. Support for some panel types is added over time, so the available types depend on your Kibana version.

vis, discover_session, markdown, and links panels can be embedded inline (full config stored in the dashboard) or linked from library (references a library item by ID).

For the full config schema for visualization panels, including chart types, metric operations, and breakdowns, refer to the Visualizations API.

• Inline: use when the panel is specific to this dashboard or must work across Kibana spaces. The panel configuration goes directly inside config:

  {
    "grid": {
      "x": 0,
      "y": 0,
      "w": 12,
      "h": 8
    },
    "type": "vis",
    "config": {
      "type": "metric",
      "title": "Average bytes",
      "data_source": {
        "type": "data_view_spec",
        "index_pattern": "kibana_sample_data_logs",
        "time_field": "timestamp"
      },
      "metrics": [
        {
          "type": "primary",
          "operation": "average",
          "field": "bytes"
        }
      ]
    }
  }
  		

• Linked from library: references an item in your library by its ID. Use ref_id with any supported panel type (vis, discover_session, markdown, links). Use the Visualizations API to create and retrieve IDs for visualization items.

  {
    "grid": {
      "x": 0,
      "y": 0,
      "w": 12,
      "h": 8
    },
    "type": "vis",
    "config": {
      "ref_id": "1e4f0a30-b3c5-11ef-bd7a-2b6b1a8c0f3d"
    }
  }
  		

To create ES|QL-based charts, embed them inline as vis panels and set data_source.type to "esql".

• metric charts: reference query result columns in metrics using column:

  {
    "grid": {
      "x": 0,
      "y": 0,
      "w": 12,
      "h": 6
    },
    "type": "vis",
    "config": {
      "type": "metric",
      "title": "Total requests",
      "data_source": {
        "type": "esql",
        "query": "FROM logs-* | STATS count = COUNT()"
      },
      "metrics": [
        {
          "type": "primary",
          "column": "count"
        }
      ]
    }
  }
  		

• xy charts: data_source goes inside each layer. Use BUCKET(@timestamp, 75, ?_tstart, ?_tend) to align time-series buckets with the dashboard's selected time range. For a complete xy chart example, see the Create a dashboard endpoint.