Upsert a Discover session

Base URL
https://{kibana_url}
Auth

Creates a Discover session with the specified ID, or fully replaces the existing session.

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 unique ID of the Discover session to create or replace.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

description string · max length: 10000

A short description of the Discover session.

tabs union anyOf[] · min items: 1 · max items: 25 required

Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference.

Any of:
breakdown_field string · max length: 1000

Field name used to split chart data into series.

chart_interval enum

Time interval for the chart histogram on this tab.

Values: auto ms s m h d w M y
column_order string[] · max items: 100

Ordered list of field names to display in the data table. If omitted, defaults to the defaultColumns advanced setting.

column_settings map string to object

Per-column settings keyed by field name, such as width. Keys should correspond to entries in column_order when both are set.

<string> object
width number · min: 0

Optional width of the column in pixels.

control_panels object[] · max items: 1000

The ES|QL controls of the tab.

config union oneOf required

The ES|QL control settings, including its variable, available options, and selected values.

One of: (determined by control_type)
control_type: STATIC_VALUES

An ES|QL variable control with a fixed list of selectable options defined directly in available_options.

control_type enum required
Values: STATIC_VALUES
available_options string[] · max items: 1000 required

A fixed list of option strings displayed in the control.

display_settings object
hide_action_bar boolean

When true, the search bar, sorting options, and select all toggle are hidden from the control.

hide_exclude boolean

When true, the exclude mode toggle is hidden from the control.

hide_exists boolean

When true, the exists filter option is hidden from the control.

hide_sort boolean

When true, the sort selector is hidden from the control.

placeholder string

Placeholder text displayed in the control input when no option is selected.

selected_options string[] · max items: 10000 required

The list of currently selected option values.

single_select boolean · default: true

When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.

title string

A human-readable title for the control.

variable_name string required

The name of the ES|QL variable that this control populates. The variable is referenced in ES|QL queries using the ?variable_name syntax.

variable_type enum required

The ES|QL variable type that determines how the selected value is substituted into the query. Accepts fields, values, functions, time_literal, or multi_values.

Values: fields values functions time_literal multi_values
grow boolean · default: false

When true, the control expands to fill any available horizontal space.

id string · min length: 1 required

The unique ID of the control.

type enum required
Values: esql_control
width enum · default: medium

The minimum width of the control.

Values: small medium large
data_source union oneOf required

The data view used by the tab, specified by reference or defined inline.

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

default_rendered_nodes number · min: 10 · max: 200

The number of nodes each JSON cell renders by default in the JSON document view.

density enum

The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.

Values: compact expanded normal
documents_display_mode enum

How documents are shown: table for a formatted table or json for a raw JSON tree.

Values: table json
filters union oneOf[] · max items: 100 · default: []

List of filters to apply to the data in the tab.

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.

header_row_height union number | enum

The table header row height, as a number of lines, or auto to size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference.

Values: auto
hide_aggregated_preview boolean

Applies to the field statistics view. When true, hides the distribution preview shown for each field. If omitted, previews are shown.

hide_chart boolean · default: false

When true, the chart is hidden.

hide_nulls boolean

When true, fields with null values are hidden in the JSON document view.

hide_table boolean · default: false

When true, the data table is hidden.

id string · min length: 1 · max length: 250 required

A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.

label string · max length: 120 required

The label of the tab.

query object

A search query consisting of an expression and its language. Supports KQL and Lucene syntax.

expression string required

A query expression in KQL or Lucene syntax.

language enum required

Query language. Use kql for Kibana Query Language (KQL) or lucene for Lucene query syntax.

Values: kql lucene
refresh_interval object

Specifies the auto-refresh interval for the object.

pause boolean required

When true, auto-refresh is paused.

value number required

The refresh interval in milliseconds.

row_height union number | enum

The table data row height, as a number of lines, or auto to size it based on content. If omitted, defaults to the discover:rowHeightOption advanced setting.

Values: auto
rows_per_page number · min: 1 · max: 10000

The number of rows to display per page in the data table. If omitted, defaults to the discover:sampleRowsPerPage advanced setting. Has no effect on ES|QL tabs.

sample_size number · min: 10 · max: 10000

The number of documents to sample for the data table. If omitted, defaults to the discover:sampleSize advanced setting.

sort object[] · max items: 100 · default: []

Sort configuration for the data table (field and direction).

direction enum required

The sort direction: asc for ascending or desc for descending.

Values: asc desc
name string required

The name of the field to sort by.

time_range object

Specifies the time range for a query.

from string required

The start of the time range. Accepts Elasticsearch date math expressions (for example, now-7d) or ISO 8601 timestamps.

mode enum

The time range mode. Use absolute for fixed start and end timestamps. Use relative for date math expressions that are re-evaluated at query time (for example, now-7d).

Values: absolute relative
to string required

The end of the time range. Accepts Elasticsearch date math expressions (for example, now) or ISO 8601 timestamps.

type enum · default: default

The tab type. default tabs have no type-specific settings.

Values: default
view_mode enum · default: documents

The Discover view mode: documents (search hits), patterns (pattern analysis), or aggregated (field statistics).

Values: documents patterns aggregated
vis_context object

The saved chart configuration. Discover reuses it when compatible with the tab’s current settings and query results; otherwise, it rebuilds the chart.

attributes map string to object required

Lens visualization attributes used to render the Discover chart.

suggestion_type enum required

Chart suggestion type used by Discover to generate this histogram configuration.

Values: lensSuggestion histogramForESQL histogramForDataView
wrap_lines boolean

When true, long values wrap in the JSON document view. When false, they are truncated to a single line.

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

Tag IDs to associate with this Discover session.

title string · min length: 1 · max length: 1000 required

The title of the Discover session.

Responses

Updated

application/json
data object required

Configuration data for a Discover session.

description string · max length: 10000

A short description of the Discover session.

tabs union anyOf[] · min items: 1 · max items: 25 required

Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference.

Same options as tabs
tags string[] · max items: 1000 · default: []

Tag IDs to associate with this Discover session.

title string · min length: 1 · max length: 1000 required

The title of the Discover session.

id string required

The Discover session ID.

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.

Created

application/json
data object required

Configuration data for a Discover session.

description string · max length: 10000

A short description of the Discover session.

tabs union anyOf[] · min items: 1 · max items: 25 required

Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference.

Same options as tabs
tags string[] · max items: 1000 · default: []

Tag IDs to associate with this Discover session.

title string · min length: 1 · max length: 1000 required

The title of the Discover session.

id string required

The Discover session ID.

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

Invalid request

403

Forbidden

409

Conflict

Base URL
https://{kibana_url}