Upsert a Discover session
- Base URL
-
https://{kibana_url}
- PUT /api/discover_sessions/{id}
- PUT /s/{space_id}/api/discover_sessions/{id}
Creates a Discover session with the specified ID, or fully replaces the existing session.
Path parameters
-
space_idstringoptional -
An identifier for the space. If
space_idis not provided in the URL, the default space is used. Refer to Spaces for more information.
Request body
-
tabsunion anyOf[] · min items: 1 · max items: 25required -
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:
-
chart_intervalenum -
Time interval for the chart histogram on this tab.
-
Values:
automssmhdwMy -
column_orderstring[] · max items: 100 -
Ordered list of field names to display in the data table. If omitted, defaults to the
defaultColumnsadvanced setting. -
column_settingsmap string to object -
Per-column settings keyed by field name, such as width. Keys should correspond to entries in
column_orderwhen both are set. -
control_panelsobject[] · max items: 1000 -
The ES|QL controls of the tab.
-
configunion oneOfrequired -
The ES|QL control settings, including its variable, available options, and selected values.
-
One of:
(determined by
control_type) -
data_sourceunion oneOfrequired -
The data view used by the tab, specified by reference or defined inline.
-
One of:
(determined by
type) -
field_filtersstring[] · max items: 10000 -
Field filters can be used to exclude one or more fields when fetching a document. They may contain wildcards, such as
user*which filters fields starting with 'user'. -
field_settingsmap string to anyOf -
Settings for individual fields, keyed by field name. To change how Kibana displays a field from the backing indices, set its label, description, or format. To define a runtime field, use the runtime field name and set
type. -
<string>union anyOf -
fieldsmap string to objectrequired -
<string>object -
custom_descriptionstring · min length: 1 -
Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
-
custom_labelstring · min length: 1 -
Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
-
formatunion anyOf -
Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
- Any of:
-
paramsobject -
patternstring -
Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
-
paramsunion oneOfrequired -
One of:
(determined by
field_type) -
patternstring -
Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
-
paramsobject -
patternstring · default: MMM D, YYYY @ HH:mm:ss.SSSSSSSSS -
Moment.js format pattern. See https://momentjs.com/ to learn more.
-
paramsobject -
patternstring · default: MMM D, YYYY @ HH:mm:ss.SSS -
Moment.js format pattern. See https://momentjs.com/ to learn more.
-
paramsobjectrequired -
include_space_with_suffixboolean · default: true -
When true or not provided, the formatted duration includes a space between the value and suffix. When false, no space is included.
-
input_formatenumrequired -
The unit of the field value before formatting.
-
Values:
picosecondsnanosecondsmicrosecondsmillisecondssecondsminuteshoursdaysweeksmonthsyears -
output_formatenumrequired -
The unit to convert the field value into for display.
-
Values:
humanizehumanize_preciseas_millisecondsas_secondsas_minutesas_hoursas_daysas_weeksas_monthsas_years -
paramsobjectrequired -
patternstring -
Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
-
paramsobject -
patternstring -
Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
-
paramsobject -
patternstring -
Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
-
paramsunion oneOfrequired -
One of:
(determined by
type) -
label_templatestring -
The template to use for the label. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are:
{{value}},{{rawValue}}and{{url}}. For example: "{{value}}". -
open_link_in_current_tabboolean -
When true, the URL opens in the current tab. When false or not provided, the URL opens in a new tab.
-
url_templatestring -
The template to use for the URL. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are:
{{value}},{{rawValue}}and{{risonValue}}. Use{{risonValue}}when embedding the field value inside Kibana app URL rison state (for example: query:'{{risonValue}}'). For example: "https://example.com/{{value}}". -
heightnumber -
The height of the image. If not provided, the image will be displayed at the original height.
-
label_templatestring -
The template to use for the label. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are:
{{value}},{{rawValue}}and{{url}}. For example: "{{value}}". -
url_templatestring -
The template to use for the URL. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are:
{{value}},{{rawValue}}and{{risonValue}}. Use{{risonValue}}when embedding the field value inside Kibana app URL rison state (for example: query:'{{risonValue}}'). For example: "https://example.com/{{value}}". -
label_templatestring -
The template to use for the label. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are:
{{value}},{{rawValue}}and{{url}}. For example: "{{value}}". -
url_templatestring -
The template to use for the URL. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are:
{{value}},{{rawValue}}and{{risonValue}}. Use{{risonValue}}when embedding the field value inside Kibana app URL rison state (for example: query:'{{risonValue}}'). For example: "https://example.com/{{value}}". -
custom_descriptionstring · min length: 1 -
Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
-
custom_labelstring · min length: 1 -
Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
-
formatunion anyOf -
Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
-
Same options as
formatinfields -
custom_descriptionstring · min length: 1 -
Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
-
custom_labelstring · min length: 1 -
Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
-
formatunion anyOf -
Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
-
Same options as
formatinfields -
index_patternstring · min length: 1required -
The index pattern (Elasticsearch index expression) to use as the data source. Example: "my-index-*".
-
default_rendered_nodesnumber · min: 10 · max: 200 -
The number of nodes each JSON cell renders by default in the JSON document view.
-
densityenum -
The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
-
Values:
compactexpandednormal -
documents_display_modeenum -
How documents are shown:
tablefor a formatted table orjsonfor a raw JSON tree. -
Values:
tablejson -
filtersunion oneOf[] · max items: 100 · default: [] -
List of filters to apply to the data in the tab.
- One of:
-
conditionunion oneOfrequired -
A filter condition with strict operator/value type matching.
-
One of:
(determined by
operator) -
negateboolean -
When
true, the filter is negated and matches documents that do NOT satisfy the condition. Defaults tofalse. -
valueobjectrequired -
Boundary values for a range comparison.
-
formatstring -
Elasticsearch date format string applied when parsing date boundary values. For example,
strict_date_optional_timeorepoch_millis. -
controlled_bystring -
Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.
-
disabledboolean -
When
true, the filter is inactive and does not affect query results. Defaults tofalse. -
controlled_bystring -
Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.
-
disabledboolean -
When
true, the filter is inactive and does not affect query results. Defaults tofalse. -
fieldstring -
Field name for scripted filters where the field cannot be extracted from the DSL query.
-
is_multi_indexboolean -
When
true, the filter can be applied across multiple indices. Defaults tofalse. -
header_row_heightunion number | enum -
The table header row height, as a number of lines, or
autoto size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference. -
Values:
auto -
hide_aggregated_previewboolean -
Applies to the field statistics view. When
true, hides the distribution preview shown for each field. If omitted, previews are shown. -
idstring · min length: 1 · max length: 250required -
A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
-
queryobject -
A search query consisting of an expression and its language. Supports KQL and Lucene syntax.
-
row_heightunion number | enum -
The table data row height, as a number of lines, or
autoto size it based on content. If omitted, defaults to thediscover:rowHeightOptionadvanced setting. -
Values:
auto -
rows_per_pagenumber · min: 1 · max: 10000 -
The number of rows to display per page in the data table. If omitted, defaults to the
discover:sampleRowsPerPageadvanced setting. Has no effect on ES|QL tabs. -
sample_sizenumber · min: 10 · max: 10000 -
The number of documents to sample for the data table. If omitted, defaults to the
discover:sampleSizeadvanced setting. -
sortobject[] · max items: 100 · default: [] -
Sort configuration for the data table (field and direction).
-
time_rangeobject -
Specifies the time range for a query.
-
fromstringrequired -
The start of the time range. Accepts Elasticsearch date math expressions (for example,
now-7d) or ISO 8601 timestamps. -
modeenum -
The time range mode. Use
absolutefor fixed start and end timestamps. Userelativefor date math expressions that are re-evaluated at query time (for example,now-7d). -
Values:
absoluterelative -
tostringrequired -
The end of the time range. Accepts Elasticsearch date math expressions (for example,
now) or ISO 8601 timestamps. -
typeenum · default: default -
The tab type.
defaulttabs have no type-specific settings. -
Values:
default -
view_modeenum · default: documents -
The Discover view mode:
documents(search hits),patterns(pattern analysis), oraggregated(field statistics). -
Values:
documentspatternsaggregated -
column_orderstring[] · max items: 100 -
Ordered list of field names to display in the data table. If omitted, defaults to the
defaultColumnsadvanced setting. -
column_settingsmap string to object -
Per-column settings keyed by field name, such as width. Keys should correspond to entries in
column_orderwhen both are set. -
control_panelsobject[] · max items: 1000 -
The ES|QL controls of the tab.
-
Same fields as
control_panelsinheader_row_height: auto -
data_sourceobjectrequired -
Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields.
-
default_rendered_nodesnumber · min: 10 · max: 200 -
The number of nodes each JSON cell renders by default in the JSON document view.
-
densityenum -
The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
-
Values:
compactexpandednormal -
documents_display_modeenum -
How documents are shown:
tablefor a formatted table orjsonfor a raw JSON tree. -
Values:
tablejson -
esql_approximationboolean -
When
true, ES|QL visualizations that useSTATSrun with approximate execution for faster, estimated results. -
header_row_heightunion number | enum -
The table header row height, as a number of lines, or
autoto size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference. -
Values:
auto -
idstring · min length: 1 · max length: 250required -
A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
-
row_heightunion number | enum -
The table data row height, as a number of lines, or
autoto size it based on content. If omitted, defaults to thediscover:rowHeightOptionadvanced setting. -
Values:
auto -
rows_per_pagenumber · min: 1 · max: 10000 -
The number of rows to display per page in the data table. If omitted, defaults to the
discover:sampleRowsPerPageadvanced setting. Has no effect on ES|QL tabs. -
sortobject[] · max items: 100 · default: [] -
Sort configuration for the data table (field and direction).
-
time_rangeobject -
Specifies the time range for a query.
-
fromstringrequired -
The start of the time range. Accepts Elasticsearch date math expressions (for example,
now-7d) or ISO 8601 timestamps. -
modeenum -
The time range mode. Use
absolutefor fixed start and end timestamps. Userelativefor date math expressions that are re-evaluated at query time (for example,now-7d). -
Values:
absoluterelative -
tostringrequired -
The end of the time range. Accepts Elasticsearch date math expressions (for example,
now) or ISO 8601 timestamps. -
typeenum · default: default -
The tab type.
defaulttabs have no type-specific settings. -
Values:
default -
column_orderstring[] · max items: 100 -
Ordered list of field names to display in the data table. If omitted, defaults to the
defaultColumnsadvanced setting. -
column_settingsmap string to object -
Per-column settings keyed by field name, such as width. Keys should correspond to entries in
column_orderwhen both are set. -
control_panelsobject[] · max items: 1000 -
The ES|QL controls of the tab.
-
Same fields as
control_panelsinheader_row_height: auto -
counter_aggregationenumrequired -
Aggregation applied to counter metric fields.
-
Values:
avgsumminmax -
data_sourceobjectrequired -
Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields.
-
default_rendered_nodesnumber · min: 10 · max: 200 -
The number of nodes each JSON cell renders by default in the JSON document view.
-
densityenum -
The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
-
Values:
compactexpandednormal -
documents_display_modeenum -
How documents are shown:
tablefor a formatted table orjsonfor a raw JSON tree. -
Values:
tablejson -
esql_approximationboolean -
When
true, ES|QL visualizations that useSTATSrun with approximate execution for faster, estimated results. -
grid_sort_directionenum -
Direction of the metrics grid order. If omitted, defaults to ascending.
-
Values:
ascdesc -
grid_sort_fieldenum -
Criterion used to order metrics in the metrics grid.
recencyorders by the metrics the viewing user explored most recently in their own browser. If omitted, metrics are ordered alphabetically. -
Values:
alphabeticallyrecency -
header_row_heightunion number | enum -
The table header row height, as a number of lines, or
autoto size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference. -
Values:
auto -
histogram_percentileenumrequired -
Percentile displayed for histogram metric fields.
-
Values:
p50p75p90p95p99 -
idstring · min length: 1 · max length: 250required -
A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
-
row_heightunion number | enum -
The table data row height, as a number of lines, or
autoto size it based on content. If omitted, defaults to thediscover:rowHeightOptionadvanced setting. -
Values:
auto -
rows_per_pagenumber · min: 1 · max: 10000 -
The number of rows to display per page in the data table. If omitted, defaults to the
discover:sampleRowsPerPageadvanced setting. Has no effect on ES|QL tabs. -
search_termstring · max length: 1000required -
Search term used to filter metrics in the metrics grid.
-
sortobject[] · max items: 100 · default: [] -
Sort configuration for the data table (field and direction).
-
time_rangeobject -
Specifies the time range for a query.
-
fromstringrequired -
The start of the time range. Accepts Elasticsearch date math expressions (for example,
now-7d) or ISO 8601 timestamps. -
modeenum -
The time range mode. Use
absolutefor fixed start and end timestamps. Userelativefor date math expressions that are re-evaluated at query time (for example,now-7d). -
Values:
absoluterelative -
tostringrequired -
The end of the time range. Accepts Elasticsearch date math expressions (for example,
now) or ISO 8601 timestamps. -
typeenumrequired -
A tab with saved metrics grid settings. Requires an ES|QL data source. These settings are used only when the query supports the metrics experience.
-
Values:
metrics
control_type: STATIC_VALUES
An ES|QL variable control with a fixed list of selectable options defined directly in available_options.
control_type: VALUES_FROM_QUERY
An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query.
type: data_view_reference
type: data_view_spec
Formats a field into a bytes value following the numeral.js format pattern. The default pattern is defined by the format:bytes:defaultPattern advanced setting.
Formats a field into a color value.
field_type: string
field_type: number
field_type: boolean
Formats a field into a currency value. The format is determined by the pattern of the format:currency:defaultPattern advanced setting.
Formats a field into a date nanos value following the defined pattern.
Formats a field into a date value following the defined pattern.
Formats a field into a duration value.
Formats a field into a geo point value.
Formats a histogram field into a numeric value following the defined pattern. The default pattern is defined by format:bytes:defaultPattern, format:percent:defaultPattern or format:number:defaultPattern advanced settings depending on the selected format.
Formats a field into a numeric value following the defined pattern. The default pattern is defined by format:number:defaultPattern advanced setting.
Formats a field into a percentage value following the defined pattern. The default pattern is defined by format:percent:defaultPattern advanced setting.
Formats a field into a relative date value. For example: "1 day ago".
Formats a field into a static value based on the lookup entries or the unknown key value.
Formats a field into a string value.
Truncates the field value to the specified length. If the field value is longer than the specified length, it will be truncated and the remaining text will be replaced with "...".
Formats a field into a link, image or audio.
type: a
type: img
type: audio
Display overrides for a field. These settings can define a custom label, description, and format.
A filter that evaluates a single field condition such as equality, range, or existence.
operator: is
Matches documents where field equals a single specified value.
operator: is_one_of
Matches documents where field equals any value in a provided list.
operator: range
Matches documents where field falls within a specified numeric or date range.
operator: exists
Matches documents where field exists and contains a non-null value.
A filter that combines multiple conditions or nested groups using a logical and or or operator.
A filter expressed as a raw Elasticsearch Query DSL object, used for queries that cannot be represented by condition or group filters.
A filter that applies an Elasticsearch geo query, used for geographic boundary and shape matching.
An ES|QL tab with saved metrics grid settings.
Responses
Updated
-
dataobjectrequired -
Configuration data for a Discover session.
-
tabsunion anyOf[] · min items: 1 · max items: 25required -
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
Created
-
dataobjectrequired -
Configuration data for a Discover session.
-
tabsunion anyOf[] · min items: 1 · max items: 25required -
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
Invalid request
Forbidden
Conflict