Kibana Dashboards and Visualizations APIs

Technical preview — These APIs are available as technical preview on Elastic Cloud Serverless projects and Kibana 9.4.

Use the Kibana Dashboards and Visualizations APIs to programmatically create, retrieve, update, and delete dashboards and visualizations.

To interact with these APIs, use the following HTTP methods:

• GET: Retrieve a resource.
• POST: Create a new resource.
• PUT: Replace an existing resource.
• DELETE: Remove a resource.

You can prepend any Kibana API endpoint with kbn: and run the request in Dev Tools → Console. For example:

GET kbn:/api/dashboards

For more information about the console, refer to Run API requests.

Note - This documentation is derived from the main branch of the kibana repository and is provided under Attribution-NonCommercial-NoDerivatives 4.0 International.

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.

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.

Try it now

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.

Dashboard structure

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.

Panel types

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

Additional panel types for observability use cases:

info The following panel types are supported in the Kibana UI but not yet by the REST API: map, legacy_vis, links, field_stats_table, aiops_change_point_chart, aiops_log_rate_analysis, aiops_pattern_analysis. Write operations (POST, PUT) return a 400 error when these panel types are included. Read operations (GET) strip these panels from the response and include them in a list of warnings.

Embedding library items

vis, discover_session, and markdown 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). 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"
    }
  }
  

ES|QL visualizations

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.

Create, retrieve, update, and delete Kibana visualizations. Visualizations created through this API are saved to your visualization library.

• Use this API to create reusable charts saved to the visualization library. You can then embed them in dashboards by referencing their ID from the Dashboards API.
• Use the Dashboards API when you want to define a complete dashboard in one request, or when you need ES|QL-based visualizations.

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.

Try it now

The following example creates a line chart showing log entries over time. You can run it after installing the Kibana sample logs dataset:

curl -X POST "${KIBANA_URL}/api/visualizations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "xy",
    "title": "Total log entries over time",
    "layers": [
      {
        "type": "line",
        "data_source": {
          "type": "data_view_spec",
          "index_pattern": "kibana_sample_data_logs",
          "time_field": "timestamp"
        },
        "x": {
          "operation": "date_histogram",
          "field": "timestamp"
        },
        "y": [
          {
            "operation": "count"
          }
        ]
      }
    ]
  }'

All curl examples in this reference use Kibana sample datasets (kibana_sample_data_logs, kibana_sample_data_ecommerce, kibana_sample_data_flights). To use your own data, replace the index_pattern and field names.

How a visualization is structured

Every visualization requires at minimum:

• type: the chart to render. Each chart type has its own required fields, so the full structure of the request body depends on which type you specify.
• data_source: how data is fetched. You can reference an existing Kibana data view by ID ("type": "data_view_reference"), define a data view inline using an index pattern ("type": "data_view_spec"), or use an ES|QL query ("type": "esql"). Note that ES|QL is only supported via the Dashboards API. For most chart types, data_source is a top-level field. For XY charts, it belongs inside each layer in layers[].

You can also include query and filters to apply KQL or Lucene filters to all chart data. Both are optional and can be omitted.

Everything else is chart-specific: layers for XY charts, metrics for metric charts, and so on. Refer to the request schema on the Create a visualization endpoint for the full shape of each type.

Chart types

The type field in the request body determines the chart type: