Get a Discover session | Kibana API documentation

Get a Discover session Generally available; added in 9.6.0

GET /api/discover_sessions/{id}

Api key auth Basic auth

Spaces method and path for this operation:

get /s/{space_id}/api/discover_sessions/{id}

Refer to Spaces for more information.

Returns the complete state of a Discover session by ID.

Path parameters

id string Required

The Discover session ID, as returned by the create or search endpoints.

Responses

200 application/json

Success
Hide response attributes Show response attributes object
- data object Required
  
  Configuration data for a Discover session.
  
  Additional properties are NOT allowed.
  
  Hide data attributes Show data attributes object
  
  description string
  
  A short description of the Discover session.
  
  Maximum length is 10000. Default value is empty.
  
  tabs array[object] Required
  
  Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference.
  
  At least 1 but not more than 25 elements.
  
  A Discover tab definition. data_source.type identifies the data source; type identifies the tab type. The tab type describes the saved settings and does not change how Discover displays the tab. Default tabs support data views and ES|QL; metrics tabs support only ES|QL.
  
  Any of:
  object-1 object object-2 object Metrics tab object
  
  Hide attributes Show attributes
  
  breakdown_field string
  
  Field name used to split chart data into series.
  
  Maximum length is 1000.
  
  chart_interval string
  
  Time interval for the chart histogram on this tab.
  
  Values are auto, ms, s, m, h, d, w, M, or y.
  
  column_order array[string]
  
  Ordered list of field names to display in the data table. If omitted, defaults to the defaultColumns advanced setting.
  
  Not more than 100 elements.
  
  column_settings object
  
  Per-column settings keyed by field name, such as width. Keys should correspond to entries in column_order when both are set.
  
  Hide column_settings attribute Show column_settings attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attribute Show * attribute object
  
  width number
  
  Optional width of the column in pixels.
  
  Minimum value is 0.
  
  control_panels array[object]
  
  The ES|QL controls of the tab.
  
  Not more than 1000 elements.
  
  Hide control_panels attributes Show control_panels attributes object
  
  An ES|QL variable control whose selected value is injected into Discover ES|QL queries using the ?variable_name syntax.
  
  config object Required
  The ES|QL control settings, including its variable, available options, and selected values.
  
  One of:
  STATIC_VALUES object VALUES_FROM_QUERY object
  
  An ES|QL variable control with a fixed list of selectable options defined directly in available_options.
  
  Hide attributes Show attributes
  
  available_options array[string] Required
  
  A fixed list of option strings displayed in the control.
  
  Not more than 1000 elements.
  
  control_type string Required Discriminator
  
  Value is STATIC_VALUES.
  
  display_settings object
  
  Additional properties are NOT allowed.
  
  Hide display_settings attributes Show display_settings attributes 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 array[string] Required
  
  The list of currently selected option values.
  
  Not more than 10000 elements.
  
  single_select boolean
  
  When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.
  
  Default value is 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 string 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.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string string-5 string
  
  Value is fields.
  
  Value is values.
  
  Value is functions.
  
  Value is time_literal.
  
  Value is multi_values.
  
  An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query.
  
  Hide attributes Show attributes
  
  control_type string Required Discriminator
  
  Value is VALUES_FROM_QUERY.
  
  display_settings object
  
  Additional properties are NOT allowed.
  
  Hide display_settings attributes Show display_settings attributes 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.
  
  esql_query string Required
  
  An ES|QL query whose results populate the list of available options in the control popover.
  
  selected_options array[string] Required
  
  The list of currently selected option values.
  
  Not more than 10000 elements.
  
  single_select boolean
  
  When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.
  
  Default value is 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 string 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.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string string-5 string
  
  Value is fields.
  
  Value is values.
  
  Value is functions.
  
  Value is time_literal.
  
  Value is multi_values.
  
  grow boolean
  
  When true, the control expands to fill any available horizontal space.
  
  Default value is false.
  
  id string Required
  
  The unique ID of the control.
  
  Minimum length is 1.
  
  type string Required
  
  Value is esql_control.
  
  width string
  
  The minimum width of the control.
  
  Values are small, medium, or large. Default value is medium.
  
  data_source object Required
  The data view used by the tab, specified by reference or defined inline.
  
  One of:
  data_view_reference object data_view_spec object
  
  Hide attributes Show attributes
  
  ref_id string Required
  
  The id of the Kibana data view to use as the data source. Example: "my-data-view".
  
  type string Required Discriminator
  
  Value is data_view_reference.
  
  Hide attributes Show attributes
  
  allow_hidden_indices boolean
  
  When true, allows the data view to match hidden indices.
  
  field_filters array[string]
  
  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'.
  
  Not more than 10000 elements. Minimum length of each is 1, maximum length of each is 1000.
  
  field_settings object
  
  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.
  
  index_pattern string Required
  
  The index pattern (Elasticsearch index expression) to use as the data source. Example: "my-index-*".
  
  Minimum length is 1.
  
  name string
  
  The name of the data view. Example: "Sample data view".
  
  Minimum length is 1, maximum length is 256.
  
  time_field string
  
  The name of the time field in the index. Used for time-based filtering. Example: "@timestamp".
  
  type string Required Discriminator
  
  Value is data_view_spec.
  
  default_rendered_nodes number
  
  The number of nodes each JSON cell renders by default in the JSON document view.
  
  Minimum value is 10, maximum value is 200.
  
  density string
  
  The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
  
  Values are compact, expanded, or normal.
  
  documents_display_mode string
  
  How documents are shown: table for a formatted table or json for a raw JSON tree.
  
  Values are table or json.
  
  filters array[object]
  
  List of filters to apply to the data in the tab.
  
  Not more than 100 elements. Default value is [] (empty).
  
  A filter applied to query results. Can be a field condition (condition), a logical group of conditions (group), a raw Elasticsearch DSL query (dsl), or a geo spatial query (spatial).
  
  One of:
  condition object group object dsl object spatial object
  
  A filter that evaluates a single field condition such as equality, range, or existence.
  
  Hide attributes Show attributes
  
  condition object Required
  A filter condition with strict operator/value type matching.
  
  One of:
  is object is_one_of object range object exists object
  
  Matches documents where field equals a single specified value.
  
  Hide attributes Show attributes
  
  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.
  
  operator string Required Discriminator
  
  Value is is.
  
  value string | number | boolean Required
  Single value to compare against the field.
  
  Any of:
  value string value number value boolean
  
  Matches documents where field equals any value in a provided list.
  
  Hide attributes Show attributes
  
  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.
  
  operator string Required Discriminator
  
  Value is is_one_of.
  
  value array[string] | array[number] | array[boolean] Required
  Homogeneous array of values to match against the field.
  
  Any of:
  array-1 array[string] array-2 array[number] array-3 array[boolean]
  
  Not more than 10000 elements.
  
  Not more than 10000 elements.
  
  Not more than 10000 elements.
  
  Matches documents where field falls within a specified numeric or date range.
  
  Hide attributes Show attributes
  
  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.
  
  operator string Required Discriminator
  
  Value is range.
  
  value object Required
  
  Boundary values for a range comparison.
  
  Additional properties are NOT allowed.
  
  Hide value attributes Show value attributes object
  
  format string
  
  Elasticsearch date format string applied when parsing date boundary values. For example, strict_date_optional_time or epoch_millis.
  
  gt number | string
  Greater than.
  
  Any of:
  number-1 number string-2 string
  
  gte number | string
  Greater than or equal to.
  
  Any of:
  number-1 number string-2 string
  
  lt number | string
  Less than.
  
  Any of:
  number-1 number string-2 string
  
  lte number | string
  Less than or equal to.
  
  Any of:
  number-1 number string-2 string
  
  Matches documents where field exists and contains a non-null value.
  
  Hide attributes Show attributes
  
  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.
  
  operator string Required Discriminator
  
  Value is exists.
  
  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.
  
  type string Required Discriminator
  
  Value is condition.
  
  A filter that combines multiple conditions or nested groups using a logical and or or operator.
  
  Hide attributes Show attributes
  
  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.
  
  group object Required
  
  Logical group that combines one or more conditions or nested groups.
  
  Additional properties are NOT allowed.
  
  Hide group attributes Show group attributes object
  
  conditions array[object] Required
  
  Ordered list of conditions or nested groups combined by the group operator.
  
  Any of:
  is is_one_of range exists Kibana_HTTP_APIs_kbn-as-code-filters-schema_groupConditionSchema object
  
  Matches documents where field equals a single specified value.
  
  Hide attributes Show attributes
  
  operator Required Discriminator
  
  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
  
  Matches documents where field equals any value in a provided list.
  
  Hide attributes Show attributes
  
  operator Required Discriminator
  
  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
  
  Matches documents where field falls within a specified numeric or date range.
  
  Hide attributes Show attributes
  
  operator Required Discriminator
  
  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 object Required
  
  Boundary values for a range comparison.
  
  Additional properties are NOT allowed.
  
  Matches documents where field exists and contains a non-null value.
  
  Hide attributes Show attributes
  
  operator Required Discriminator
  
  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.
  
  Logical group that combines one or more conditions or nested groups.
  
  Additional properties are NOT allowed.
  
  operator string Required
  Logical operator applied across all entries in conditions. Use and to require all conditions, or or to require at least one.
  
  Any of:
  string-1 string string-2 string
  
  Value is and.
  
  Value is or.
  
  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.
  
  type string Required Discriminator
  
  Value is group.
  
  A filter expressed as a raw Elasticsearch Query DSL object, used for queries that cannot be represented by condition or group filters.
  
  Hide attributes Show attributes
  
  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.
  
  dsl object Required
  
  Elasticsearch Query DSL object passed directly to the query.
  
  Additional properties are allowed.
  
  field string
  
  Field name for scripted filters where the field cannot be extracted from the DSL query.
  
  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.
  
  params
  
  Filter parameters metadata. May contain display values, formats, and parameters for scripted filters.
  
  type string Required Discriminator
  
  Value is dsl.
  
  A filter that applies an Elasticsearch geo query, used for geographic boundary and shape matching.
  
  Hide attributes Show attributes
  
  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.
  
  dsl object Required
  
  Elasticsearch geo query DSL object.
  
  Additional properties are allowed.
  
  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.
  
  type string Required Discriminator
  
  Value is spatial.
  
  header_row_height number | string
  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.
  
  Any of:
  number-1 number string-2 string
  
  Minimum value is 1, maximum value is 5.
  
  Value is 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
  
  When true, the chart is hidden.
  
  Default value is false.
  
  hide_nulls boolean
  
  When true, fields with null values are hidden in the JSON document view.
  
  hide_table boolean
  
  When true, the data table is hidden.
  
  Default value is false.
  
  id string Required
  
  A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
  
  Minimum length is 1, maximum length is 250.
  
  label string Required
  
  The label of the tab.
  
  Maximum length is 120.
  
  query object
  
  A search query consisting of an expression and its language. Supports KQL and Lucene syntax.
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  expression string Required
  
  A query expression in KQL or Lucene syntax.
  
  language string Required
  
  Query language. Use kql for Kibana Query Language (KQL) or lucene for Lucene query syntax.
  
  Values are kql or lucene.
  
  refresh_interval object
  
  The refresh interval of the tab. Applied only when time_range is set. When omitted, Discover uses the global refresh interval.
  
  Additional properties are NOT allowed.
  
  Hide refresh_interval attributes Show refresh_interval attributes object
  
  pause boolean Required
  
  When true, auto-refresh is paused.
  
  value number Required
  
  The refresh interval in milliseconds.
  
  row_height number | string
  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.
  
  Any of:
  number-1 number string-2 string
  
  Minimum value is 1, maximum value is 20.
  
  Value is auto.
  
  rows_per_page number
  
  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.
  
  Minimum value is 1, maximum value is 10000.
  
  sample_size number
  
  The number of documents to sample for the data table. If omitted, defaults to the discover:sampleSize advanced setting.
  
  Minimum value is 10, maximum value is 10000.
  
  sort array[object]
  
  Sort configuration for the data table (field and direction).
  
  Not more than 100 elements. Default value is [] (empty).
  
  Hide sort attributes Show sort attributes object
  
  direction string Required
  
  The sort direction: asc for ascending or desc for descending.
  
  Values are asc or desc.
  
  name string Required
  
  The name of the field to sort by.
  
  time_range object
  
  Time range to restore when the tab is opened. When omitted, Discover uses the global time settings.
  
  Additional properties are NOT allowed.
  
  Hide time_range attributes Show time_range attributes object
  
  from string Required
  
  The start of the time range. Accepts Elasticsearch date math expressions (for example, now-7d) or ISO 8601 timestamps.
  
  mode string
  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).
  
  Any of:
  string-1 string string-2 string
  
  Value is absolute.
  
  Value is relative.
  
  to string Required
  
  The end of the time range. Accepts Elasticsearch date math expressions (for example, now) or ISO 8601 timestamps.
  
  type string
  
  The tab type. default tabs have no type-specific settings.
  
  Value is default. Default value is default.
  
  view_mode string
  
  The Discover view mode: documents (search hits), patterns (pattern analysis), or aggregated (field statistics).
  
  Values are documents, patterns, or aggregated. Default value is documents.
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide vis_context attributes Show vis_context attributes object
  
  attributes object Required
  
  Lens visualization attributes used to render the Discover chart.
  
  Additional properties are allowed.
  
  suggestion_type string Required
  
  Chart suggestion type used by Discover to generate this histogram configuration.
  
  Values are lensSuggestion, histogramForESQL, or histogramForDataView.
  
  wrap_lines boolean
  
  When true, long values wrap in the JSON document view. When false, they are truncated to a single line.
  
  Hide attributes Show attributes
  
  breakdown_field string
  
  Field name used to split chart data into series.
  
  Maximum length is 1000.
  
  column_order array[string]
  
  Ordered list of field names to display in the data table. If omitted, defaults to the defaultColumns advanced setting.
  
  Not more than 100 elements.
  
  column_settings object
  
  Per-column settings keyed by field name, such as width. Keys should correspond to entries in column_order when both are set.
  
  Hide column_settings attribute Show column_settings attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attribute Show * attribute object
  
  width number
  
  Optional width of the column in pixels.
  
  Minimum value is 0.
  
  control_panels array[object]
  
  The ES|QL controls of the tab.
  
  Not more than 1000 elements.
  
  Hide control_panels attributes Show control_panels attributes object
  
  An ES|QL variable control whose selected value is injected into Discover ES|QL queries using the ?variable_name syntax.
  
  config object Required
  The ES|QL control settings, including its variable, available options, and selected values.
  
  One of:
  STATIC_VALUES object VALUES_FROM_QUERY object
  
  An ES|QL variable control with a fixed list of selectable options defined directly in available_options.
  
  Hide attributes Show attributes
  
  available_options array[string] Required
  
  A fixed list of option strings displayed in the control.
  
  Not more than 1000 elements.
  
  control_type string Required Discriminator
  
  Value is STATIC_VALUES.
  
  display_settings object
  
  Additional properties are NOT allowed.
  
  Hide display_settings attributes Show display_settings attributes 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 array[string] Required
  
  The list of currently selected option values.
  
  Not more than 10000 elements.
  
  single_select boolean
  
  When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.
  
  Default value is 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 string 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.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string string-5 string
  
  Value is fields.
  
  Value is values.
  
  Value is functions.
  
  Value is time_literal.
  
  Value is multi_values.
  
  An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query.
  
  Hide attributes Show attributes
  
  control_type string Required Discriminator
  
  Value is VALUES_FROM_QUERY.
  
  display_settings object
  
  Additional properties are NOT allowed.
  
  Hide display_settings attributes Show display_settings attributes 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.
  
  esql_query string Required
  
  An ES|QL query whose results populate the list of available options in the control popover.
  
  selected_options array[string] Required
  
  The list of currently selected option values.
  
  Not more than 10000 elements.
  
  single_select boolean
  
  When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.
  
  Default value is 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 string 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.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string string-5 string
  
  Value is fields.
  
  Value is values.
  
  Value is functions.
  
  Value is time_literal.
  
  Value is multi_values.
  
  grow boolean
  
  When true, the control expands to fill any available horizontal space.
  
  Default value is false.
  
  id string Required
  
  The unique ID of the control.
  
  Minimum length is 1.
  
  type string Required
  
  Value is esql_control.
  
  width string
  
  The minimum width of the control.
  
  Values are small, medium, or large. Default value is medium.
  
  data_source object Required
  
  Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields.
  
  Additional properties are NOT allowed.
  
  Hide data_source attributes Show data_source attributes object
  
  query string Required
  
  An ES|QL query that drives the data source. The query must produce a tabular result set; column names are used as field references. Example: "FROM logs-* | STATS count = COUNT(*) BY host.name".
  
  type string Required
  
  Value is esql.
  
  default_rendered_nodes number
  
  The number of nodes each JSON cell renders by default in the JSON document view.
  
  Minimum value is 10, maximum value is 200.
  
  density string
  
  The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
  
  Values are compact, expanded, or normal.
  
  documents_display_mode string
  
  How documents are shown: table for a formatted table or json for a raw JSON tree.
  
  Values are table or json.
  
  esql_approximation boolean
  
  When true, ES|QL visualizations that use STATS run with approximate execution for faster, estimated results.
  
  header_row_height number | string
  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.
  
  Any of:
  number-1 number string-2 string
  
  Minimum value is 1, maximum value is 5.
  
  Value is auto.
  
  hide_chart boolean
  
  When true, the chart is hidden.
  
  Default value is false.
  
  hide_nulls boolean
  
  When true, fields with null values are hidden in the JSON document view.
  
  hide_table boolean
  
  When true, the data table is hidden.
  
  Default value is false.
  
  id string Required
  
  A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
  
  Minimum length is 1, maximum length is 250.
  
  label string Required
  
  The label of the tab.
  
  Maximum length is 120.
  
  refresh_interval object
  
  The refresh interval of the tab. Applied only when time_range is set. When omitted, Discover uses the global refresh interval.
  
  Additional properties are NOT allowed.
  
  Hide refresh_interval attributes Show refresh_interval attributes object
  
  pause boolean Required
  
  When true, auto-refresh is paused.
  
  value number Required
  
  The refresh interval in milliseconds.
  
  row_height number | string
  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.
  
  Any of:
  number-1 number string-2 string
  
  Minimum value is 1, maximum value is 20.
  
  Value is auto.
  
  rows_per_page number
  
  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.
  
  Minimum value is 1, maximum value is 10000.
  
  sort array[object]
  
  Sort configuration for the data table (field and direction).
  
  Not more than 100 elements. Default value is [] (empty).
  
  Hide sort attributes Show sort attributes object
  
  direction string Required
  
  The sort direction: asc for ascending or desc for descending.
  
  Values are asc or desc.
  
  name string Required
  
  The name of the field to sort by.
  
  time_range object
  
  Time range to restore when the tab is opened. When omitted, Discover uses the global time settings.
  
  Additional properties are NOT allowed.
  
  Hide time_range attributes Show time_range attributes object
  
  from string Required
  
  The start of the time range. Accepts Elasticsearch date math expressions (for example, now-7d) or ISO 8601 timestamps.
  
  mode string
  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).
  
  Any of:
  string-1 string string-2 string
  
  Value is absolute.
  
  Value is relative.
  
  to string Required
  
  The end of the time range. Accepts Elasticsearch date math expressions (for example, now) or ISO 8601 timestamps.
  
  type string
  
  The tab type. default tabs have no type-specific settings.
  
  Value is default. Default value is default.
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide vis_context attributes Show vis_context attributes object
  
  attributes object Required
  
  Lens visualization attributes used to render the Discover chart.
  
  Additional properties are allowed.
  
  suggestion_type string Required
  
  Chart suggestion type used by Discover to generate this histogram configuration.
  
  Values are lensSuggestion, histogramForESQL, or histogramForDataView.
  
  wrap_lines boolean
  
  When true, long values wrap in the JSON document view. When false, they are truncated to a single line.
  
  An ES|QL tab with saved metrics grid settings.
  
  Hide attributes Show attributes
  
  breakdown_field string
  
  Field name used to split chart data into series.
  
  Maximum length is 1000.
  
  column_order array[string]
  
  Ordered list of field names to display in the data table. If omitted, defaults to the defaultColumns advanced setting.
  
  Not more than 100 elements.
  
  column_settings object
  
  Per-column settings keyed by field name, such as width. Keys should correspond to entries in column_order when both are set.
  
  Hide column_settings attribute Show column_settings attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attribute Show * attribute object
  
  width number
  
  Optional width of the column in pixels.
  
  Minimum value is 0.
  
  control_panels array[object]
  
  The ES|QL controls of the tab.
  
  Not more than 1000 elements.
  
  Hide control_panels attributes Show control_panels attributes object
  
  An ES|QL variable control whose selected value is injected into Discover ES|QL queries using the ?variable_name syntax.
  
  config object Required
  The ES|QL control settings, including its variable, available options, and selected values.
  
  One of:
  STATIC_VALUES object VALUES_FROM_QUERY object
  
  An ES|QL variable control with a fixed list of selectable options defined directly in available_options.
  
  Hide attributes Show attributes
  
  available_options array[string] Required
  
  A fixed list of option strings displayed in the control.
  
  Not more than 1000 elements.
  
  control_type string Required Discriminator
  
  Value is STATIC_VALUES.
  
  display_settings object
  
  Additional properties are NOT allowed.
  
  Hide display_settings attributes Show display_settings attributes 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 array[string] Required
  
  The list of currently selected option values.
  
  Not more than 10000 elements.
  
  single_select boolean
  
  When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.
  
  Default value is 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 string 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.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string string-5 string
  
  Value is fields.
  
  Value is values.
  
  Value is functions.
  
  Value is time_literal.
  
  Value is multi_values.
  
  An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query.
  
  Hide attributes Show attributes
  
  control_type string Required Discriminator
  
  Value is VALUES_FROM_QUERY.
  
  display_settings object
  
  Additional properties are NOT allowed.
  
  Hide display_settings attributes Show display_settings attributes 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.
  
  esql_query string Required
  
  An ES|QL query whose results populate the list of available options in the control popover.
  
  selected_options array[string] Required
  
  The list of currently selected option values.
  
  Not more than 10000 elements.
  
  single_select boolean
  
  When true, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to true.
  
  Default value is 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 string 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.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string string-5 string
  
  Value is fields.
  
  Value is values.
  
  Value is functions.
  
  Value is time_literal.
  
  Value is multi_values.
  
  grow boolean
  
  When true, the control expands to fill any available horizontal space.
  
  Default value is false.
  
  id string Required
  
  The unique ID of the control.
  
  Minimum length is 1.
  
  type string Required
  
  Value is esql_control.
  
  width string
  
  The minimum width of the control.
  
  Values are small, medium, or large. Default value is medium.
  
  counter_aggregation string Required
  
  Aggregation applied to counter metric fields.
  
  Values are avg, sum, min, or max.
  
  data_source object Required
  
  Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields.
  
  Additional properties are NOT allowed.
  
  Hide data_source attributes Show data_source attributes object
  
  query string Required
  
  An ES|QL query that drives the data source. The query must produce a tabular result set; column names are used as field references. Example: "FROM logs-* | STATS count = COUNT(*) BY host.name".
  
  type string Required
  
  Value is esql.
  
  default_rendered_nodes number
  
  The number of nodes each JSON cell renders by default in the JSON document view.
  
  Minimum value is 10, maximum value is 200.
  
  density string
  
  The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
  
  Values are compact, expanded, or normal.
  
  dimensions array[string] Required
  
  Fields used to group metrics in the metrics grid.
  
  Not more than 5 elements. Maximum length of each is 1000.
  
  documents_display_mode string
  
  How documents are shown: table for a formatted table or json for a raw JSON tree.
  
  Values are table or json.
  
  esql_approximation boolean
  
  When true, ES|QL visualizations that use STATS run with approximate execution for faster, estimated results.
  
  gauge_aggregation string Required
  
  Aggregation applied to gauge metric fields.
  
  Values are avg, sum, min, or max.
  
  grid_sort_direction string
  
  Direction of the metrics grid order. If omitted, defaults to ascending.
  
  Values are asc or desc.
  
  grid_sort_field string
  
  Criterion used to order metrics in the metrics grid. recency orders by the metrics the viewing user explored most recently in their own browser. If omitted, metrics are ordered alphabetically.
  
  Values are alphabetically or recency.
  
  header_row_height number | string
  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.
  
  Any of:
  number-1 number string-2 string
  
  Minimum value is 1, maximum value is 5.
  
  Value is auto.
  
  hide_chart boolean
  
  When true, the chart is hidden.
  
  Default value is false.
  
  hide_nulls boolean
  
  When true, fields with null values are hidden in the JSON document view.
  
  hide_table boolean
  
  When true, the data table is hidden.
  
  Default value is false.
  
  histogram_percentile string Required
  
  Percentile displayed for histogram metric fields.
  
  Values are p50, p75, p90, p95, or p99.
  
  histogram_visualization string
  
  How histogram metrics are drawn. If omitted, Discover uses the percentile chart.
  
  Value is lnsXY.
  
  id string Required
  
  A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
  
  Minimum length is 1, maximum length is 250.
  
  label string Required
  
  The label of the tab.
  
  Maximum length is 120.
  
  refresh_interval object
  
  The refresh interval of the tab. Applied only when time_range is set. When omitted, Discover uses the global refresh interval.
  
  Additional properties are NOT allowed.
  
  Hide refresh_interval attributes Show refresh_interval attributes object
  
  pause boolean Required
  
  When true, auto-refresh is paused.
  
  value number Required
  
  The refresh interval in milliseconds.
  
  row_height number | string
  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.
  
  Any of:
  number-1 number string-2 string
  
  Minimum value is 1, maximum value is 20.
  
  Value is auto.
  
  rows_per_page number
  
  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.
  
  Minimum value is 1, maximum value is 10000.
  
  search_term string Required
  
  Search term used to filter metrics in the metrics grid.
  
  Maximum length is 1000.
  
  sort array[object]
  
  Sort configuration for the data table (field and direction).
  
  Not more than 100 elements. Default value is [] (empty).
  
  Hide sort attributes Show sort attributes object
  
  direction string Required
  
  The sort direction: asc for ascending or desc for descending.
  
  Values are asc or desc.
  
  name string Required
  
  The name of the field to sort by.
  
  time_range object
  
  Time range to restore when the tab is opened. When omitted, Discover uses the global time settings.
  
  Additional properties are NOT allowed.
  
  Hide time_range attributes Show time_range attributes object
  
  from string Required
  
  The start of the time range. Accepts Elasticsearch date math expressions (for example, now-7d) or ISO 8601 timestamps.
  
  mode string
  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).
  
  Any of:
  string-1 string string-2 string
  
  Value is absolute.
  
  Value is relative.
  
  to string Required
  
  The end of the time range. Accepts Elasticsearch date math expressions (for example, now) or ISO 8601 timestamps.
  
  type string Required
  
  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.
  
  Value is metrics.
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide vis_context attributes Show vis_context attributes object
  
  attributes object Required
  
  Lens visualization attributes used to render the Discover chart.
  
  Additional properties are allowed.
  
  suggestion_type string Required
  
  Chart suggestion type used by Discover to generate this histogram configuration.
  
  Values are lensSuggestion, histogramForESQL, or histogramForDataView.
  
  wrap_lines boolean
  
  When true, long values wrap in the JSON document view. When false, they are truncated to a single line.
  
  tags array[string]
  
  Tag IDs to associate with this Discover session.
  
  Not more than 1000 elements. Maximum length of each is 250. Default value is [] (empty).
  
  title string Required
  
  The title of the Discover session.
  
  Minimum length is 1, maximum length is 1000.
- id string Required
  
  The Discover session ID.
- meta object Required
  
  Additional properties are NOT allowed.
  
  Hide meta attributes Show meta attributes object
  
  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.
- warnings array[object]
  
  Warnings about content omitted from the API response due to conversion or validation errors. The saved session is not modified.
  
  Any of:
  Dropped item object Dropped property object
  
  An item in a tab that was excluded from the response because it failed validation.
  
  Hide attributes Show attributes
  
  item_config object
  
  The original configuration of the dropped item.
  
  Additional properties are allowed.
  
  item_id string Required
  
  The ID of the dropped item.
  
  item_type string
  
  The type identifier of the dropped item, when available.
  
  key string Required
  
  The name of the property that contains the dropped item.
  
  message string Required
  
  The reason the content was dropped.
  
  tab_id string Required
  
  The ID of the tab that contains the dropped content.
  
  type string Required
  
  Value is dropped_item.
  
  A tab property excluded from the response due to malformed data.
  
  Hide attributes Show attributes
  
  key string Required
  
  The name of the property that was dropped.
  
  message string Required
  
  The reason the content was dropped.
  
  tab_id string Required
  
  The ID of the tab that contains the dropped content.
  
  type string Required
  
  Value is dropped_property.
  
  value
  
  The original value of the property that was dropped.
403

Forbidden
404

Not found
500

Internal server error

GET /api/discover_sessions/{id}

curl -X GET "${KIBANA_URL}/api/discover_sessions/web-log-requests" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "elastic-api-version: 2023-10-31"

GET kbn:/api/discover_sessions/web-log-requests

Response examples (200)

{
  "data": {
    "description": "",
    "tabs": [
      {
        "column_order": [
          "extension",
          "requests"
        ],
        "data_source": {
          "query": "FROM kibana_sample_data_logs | STATS requests = COUNT(*) BY extension | SORT requests DESC",
          "type": "esql"
        },
        "hide_chart": false,
        "hide_table": false,
        "id": "requests",
        "label": "Requests",
        "sort": [],
        "type": "default"
      }
    ],
    "tags": [],
    "title": "Requests by extension"
  },
  "id": "web-log-requests",
  "meta": {
    "created_at": "2026-10-15T09:00:00.000Z",
    "created_by": "u_example",
    "managed": false,
    "updated_at": "2026-10-15T09:00:00.000Z",
    "updated_by": "u_example",
    "version": "WzEsMV0="
  }
}