Visualizations

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.

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.

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.

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