Upsert visualization

Base URL
https://{kibana_url}
Auth

Replaces the full configuration of an existing Lens visualization. Partial updates are not supported. To make incremental changes, retrieve the visualization first, modify the fields you need, then send the complete object back.

If no visualization exists with the specified ID, a new one is created.

ES|QL visualizations cannot be updated through this endpoint.

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

id string required

The visualization identifier, as returned by the create or search endpoints.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

Any of:
type enum required
Values: metric
breakdown_by union anyOf
Any of:
operation enum required
Values: date_histogram
collapse_by union anyOf

Aggregation function used to collapse a breakdown dimension into a single value.

Values: avg sum max min
columns number · default: 3

Number of columns.

drop_partial_intervals boolean · default: false

When true, drops partial intervals from the results.

field string required

Field to be used for the date histogram.

include_empty_rows boolean · default: true

When true, includes empty rows in the results.

label string

Label for the operation

suggested_interval string · default: auto

Suggested time interval.

use_original_time_range boolean · default: false

When true, uses the original time range instead of the current query time range.

data_source union oneOf required
One of: (determined by type)
type: data_view_reference
type enum required
Values: data_view_reference
ref_id string required

The id of the Kibana data view to use as the data source. Example: "my-data-view".

description string

The description of the chart. Optional. Any string value or undefined.

filters union oneOf[] · max items: 100

Filters applied to the panel

One of:

A filter that evaluates a single field condition such as equality, range, or existence.

type enum required
Values: condition
condition union oneOf required

A filter condition with strict operator/value type matching.

One of: (determined by operator)
operator: is

Matches documents where field equals a single specified value.

operator enum required
Values: is
field string required

Name of the document field the condition evaluates.

negate boolean

When true, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to false.

value union string | number | boolean required

Single value to compare against the field.

controlled_by string

Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.

data_view_id string

Identifier of the data view used as context for this filter.

disabled boolean

When true, the filter is inactive and does not affect query results. Defaults to false.

is_multi_index boolean

When true, the filter can be applied across multiple indices. Defaults to false.

label string

Human-readable label for the filter, used for display purposes.

negate boolean

When true, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to false.

ignore_global_filters boolean · default: false

When true, ignores global filters when fetching data for this layer. Defaults to false.

metrics union anyOf[] · min items: 1 · max items: 2 required

Metric dimensions to display. The first must be a primary metric; an optional second must be a secondary metric.

Any of:
type enum required
Values: primary
apply_color_to enum

Color target: value colors the metric text, background colors the cell or panel background.

Values: value background
background_chart union anyOf

Secondary visualization displayed behind the primary metric value, either a bar chart (with optional max value) or a trend line.

Any of:
type enum required
Values: bar
max_value union anyOf required

Metric dimension configuration, supporting field-based aggregations (count, sum, average, median, standard deviation, unique count, last value), percentile operations, time-series operations (differences, moving average, cumulative sum, counter rate), and mathematical formulas.

Any of:
operation enum required
Values: formula
format union anyOf

Number display format for the dimension value.

Same options as format in Terms Operation
formula string required

Formula

label string

Label for the operation

reduced_time_range string

Reduced time range

time_scale enum

Time scale

Values: s m h d
orientation enum

Orientation

Values: horizontal vertical
color union anyOf · default: {"type":"auto"}

Color configuration for the primary metric value or background.

Any of:

Dynamic color mapping by numeric range, with support for absolute and percentage-based ranges and for named palettes.

Any of:

Color by absolute value configuration

range enum required
Values: absolute
steps object[] · min items: 1 · max items: 100 required

Array of ordered color steps defining the range each color is applied.

color string required

The color to use for this step.

gte number nullable

The lower bound of range from which this color applies (inclusive).

lt number nullable

The upper bound of range to which this color applies (exclusive).

lte number nullable

The upper bound of range to which this color applies (inclusive).

type enum required
Values: dynamic
subtitle string

Subtitle below the primary metric value.

Any of:
empty_as_null boolean · default: false

When true, treats empty buckets as null instead of zero.

field string

Field to be used for the metric

format union anyOf

Number display format for the dimension value.

Same options as format in Terms Operation
label string

Label for the operation

operation enum required
Values: count
reduced_time_range string

Reduced time range

time_scale union anyOf

Time scale

Values: s m h d
time_shift string

Time shift

sampling number · min: 0 · max: 1 · default: 1

Sampling factor between 0 (no sampling) and 1 (full sampling).

tags string[] · max items: 1000 · default: []

Tag IDs to associate with this visualization.

title string

The title of the chart displayed in the panel. Optional. Any string value or undefined.

Responses

Ok

application/json
data union anyOf required
Any of:
type enum required
Values: metric
breakdown_by union anyOf
Same options as breakdown_by in Metric Chart (library)
data_source union oneOf required
Same options as data_source in Metric Chart (library)
description string

The description of the chart. Optional. Any string value or undefined.

filters union oneOf[] · max items: 100

Filters applied to the panel

Same options as filters in Metric Chart (library)
ignore_global_filters boolean · default: false

When true, ignores global filters when fetching data for this layer. Defaults to false.

metrics union anyOf[] · min items: 1 · max items: 2 required

Metric dimensions to display. The first must be a primary metric; an optional second must be a secondary metric.

Same options as metrics in Metric Chart (library)
sampling number · min: 0 · max: 1 · default: 1

Sampling factor between 0 (no sampling) and 1 (full sampling).

styling object

Visual chart styling options

Same fields as styling in Metric Chart (library)
tags string[] · max items: 1000 · default: []

Tag IDs to associate with this visualization.

title string

The title of the chart displayed in the panel. Optional. Any string value or undefined.

id string required
meta object required
created_at string

Timestamp when the object was created (ISO 8601).

created_by string

User profile ID of the user who created the object.

managed boolean

When true, the object is managed by Kibana and cannot be edited by users.

owner string

Identifier of the plugin or team that owns this object.

updated_at string

Timestamp when the object was last updated (ISO 8601).

updated_by string

User profile ID of the user who last updated the object.

version string

Internal version identifier for optimistic concurrency control.

400

Malformed request

401

Unauthorized

403

Forbidden

500

Internal Server Error

Base URL
https://{kibana_url}