--- title: "Upsert a Discover session" method: PUT path: "/api/discover_sessions/{id}" tags: ["Discover sessions"] --- # Upsert a Discover session `PUT /api/discover_sessions/{id}` ## Request - Base URL: `https://localhost:5601` - URL: `https://localhost:5601/api/discover_sessions/{id}` - Auth: one of: - API key in header `Authorization` - HTTP basic **Spaces method and path for this operation:**
put /s/{space_id}/api/discover_sessions/{id}
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information. Creates a Discover session with the specified ID, or fully replaces the existing session. ## Path parameters - `id` string, required ## Headers - `kbn-xsrf` string, required ## Request body - KibanaHTTPAPIsKbnDiscoverSessionData: Configuration data for a Discover session. - `description` string: A short description of the Discover session. - `tabs` union[], required: Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference. - union: 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. - object - `breakdown_field` string: Field name used to split chart data into series. - `chart_interval` 'auto' | 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'y': Time interval for the chart histogram on this tab. - `column_order` string[]: Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting. - `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. - `control_panels` KibanaHTTPAPIsKbnDiscoverSessionApiEsqlControlPanel[]: The ES|QL controls of the tab. - `config` union, required: The ES|QL control settings, including its variable, available options, and selected values. - KibanaHTTPAPIsKbnControlsSchemasOptionsListEsqlControlSchemaStaticValues: An ES|QL variable control with a fixed list of selectable options defined directly in `available_options`. - … - KibanaHTTPAPIsKbnControlsSchemasOptionsListEsqlControlSchemaValuesFromQuery: An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query. - … - `grow` boolean: When `true`, the control expands to fill any available horizontal space. - `id` string, required: The unique ID of the control. - `type` 'esql_control', required - `width` 'small' | 'medium' | 'large': The minimum width of the control. - `data_source` union, required: The data view used by the tab, specified by reference or defined inline. - KibanaHTTPAPIsKbnDataViewReferenceSchema - `ref_id` string, required: The id of the Kibana data view to use as the data source. Example: "my-data-view". - `type` 'data_view_reference', required - KibanaHTTPAPIsKbnDataViewSpecSchema - `allow_hidden_indices` boolean: When `true`, allows the data view to match hidden indices. - `field_filters` 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'. - `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-*". - `name` string: The name of the data view. Example: "Sample data view". - `time_field` string: The name of the time field in the index. Used for time-based filtering. Example: "@timestamp". - `type` 'data_view_spec', required - `default_rendered_nodes` number: The number of nodes each JSON cell renders by default in the JSON document view. - `density` 'compact' | 'expanded' | 'normal': The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference. - `documents_display_mode` 'table' | 'json': How documents are shown: `table` for a formatted table or `json` for a raw JSON tree. - `filters` KibanaHTTPAPIsKbnAsCodeFiltersSchemaAsCodeFilterSchema[]: List of filters to apply to the data in the tab. - union: 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`). - KibanaHTTPAPIsKbnAsCodeFiltersSchemaAsCodeConditionFilterSchema: A filter that evaluates a single field condition such as equality, range, or existence. - … - KibanaHTTPAPIsKbnAsCodeFiltersSchemaAsCodeGroupFilterSchema: A filter that combines multiple conditions or nested groups using a logical `and` or `or` operator. - … - KibanaHTTPAPIsKbnAsCodeFiltersSchemaAsCodeDSLFilterSchema: A filter expressed as a raw [Elasticsearch Query DSL](https://www.elastic.co/docs/reference/query-languages/querydsl) object, used for queries that cannot be represented by condition or group filters. - … - KibanaHTTPAPIsKbnAsCodeFiltersSchemaAsCodeSpatialFilterSchema: A filter that applies an Elasticsearch geo query, used for geographic boundary and shape matching. - … - `header_row_height` union: 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. - number - '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. - `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. - `id` string, required: A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores. - `label` string, required: The label of the tab. - `query` KibanaHTTPAPIsKbnAsCodeQuery: 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` 'kql' | 'lucene', required: Query language. Use `kql` for Kibana Query Language (KQL) or `lucene` for Lucene query syntax. - `refresh_interval` KibanaHTTPAPIsKbnDataServiceServerRefreshIntervalSchema: 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: 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. - number - '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. - `sample_size` number: The number of documents to sample for the data table. If omitted, defaults to the `discover:sampleSize` advanced setting. - `sort` object[]: Sort configuration for the data table (field and direction). - `direction` 'asc' | 'desc', required: The sort direction: `asc` for ascending or `desc` for descending. - `name` string, required: The name of the field to sort by. - `time_range` KibanaHTTPAPIsKbnEsQueryServerTimeRangeSchema: Specifies the time range for a query. - `from` string, required: The start of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now-7d`) or ISO 8601 timestamps. - `mode` union: The time range mode. Use `absolute` for fixed start and end timestamps. Use `relative` for [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions that are re-evaluated at query time (for example, `now-7d`). - 'absolute' - 'relative' - `to` string, required: The end of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now`) or ISO 8601 timestamps. - `type` 'default': The tab type. `default` tabs have no type-specific settings. - `view_mode` 'documents' | 'patterns' | 'aggregated': The Discover view mode: `documents` (search hits), `patterns` (pattern analysis), or `aggregated` (field statistics). - `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` object, required: Lens visualization attributes used to render the Discover chart. - `suggestion_type` 'lensSuggestion' | 'histogramForESQL' | 'histogramForDataView', required: Chart suggestion type used by Discover to generate this histogram configuration. - `wrap_lines` boolean: When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line. - object - `breakdown_field` string: Field name used to split chart data into series. - `column_order` string[]: Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting. - `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. - `control_panels` KibanaHTTPAPIsKbnDiscoverSessionApiEsqlControlPanel[]: The ES|QL controls of the tab. - `config` union, required: The ES|QL control settings, including its variable, available options, and selected values. - KibanaHTTPAPIsKbnControlsSchemasOptionsListEsqlControlSchemaStaticValues: An ES|QL variable control with a fixed list of selectable options defined directly in `available_options`. - … - KibanaHTTPAPIsKbnControlsSchemasOptionsListEsqlControlSchemaValuesFromQuery: An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query. - … - `grow` boolean: When `true`, the control expands to fill any available horizontal space. - `id` string, required: The unique ID of the control. - `type` 'esql_control', required - `width` 'small' | 'medium' | 'large': The minimum width of the control. - `data_source` KibanaHTTPAPIsEsqlDataSource, required: Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields. - `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` 'esql', required - `default_rendered_nodes` number: The number of nodes each JSON cell renders by default in the JSON document view. - `density` 'compact' | 'expanded' | 'normal': The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference. - `documents_display_mode` 'table' | 'json': How documents are shown: `table` for a formatted table or `json` for a raw JSON tree. - `esql_approximation` boolean: When `true`, ES|QL visualizations that use `STATS` run with [approximate execution](https://www.elastic.co/docs/reference/query-languages/esql/esql-query-approximation) for faster, estimated results. - `header_row_height` union: 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. - number - 'auto' - `hide_chart` boolean: 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: When `true`, the data table is hidden. - `id` string, required: A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores. - `label` string, required: The label of the tab. - `refresh_interval` KibanaHTTPAPIsKbnDataServiceServerRefreshIntervalSchema: 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: 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. - number - '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. - `sort` object[]: Sort configuration for the data table (field and direction). - `direction` 'asc' | 'desc', required: The sort direction: `asc` for ascending or `desc` for descending. - `name` string, required: The name of the field to sort by. - `time_range` KibanaHTTPAPIsKbnEsQueryServerTimeRangeSchema: Specifies the time range for a query. - `from` string, required: The start of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now-7d`) or ISO 8601 timestamps. - `mode` union: The time range mode. Use `absolute` for fixed start and end timestamps. Use `relative` for [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions that are re-evaluated at query time (for example, `now-7d`). - 'absolute' - 'relative' - `to` string, required: The end of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now`) or ISO 8601 timestamps. - `type` 'default': The tab type. `default` tabs have no type-specific settings. - `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` object, required: Lens visualization attributes used to render the Discover chart. - `suggestion_type` 'lensSuggestion' | 'histogramForESQL' | 'histogramForDataView', required: Chart suggestion type used by Discover to generate this histogram configuration. - `wrap_lines` boolean: When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line. - object: An ES|QL tab with saved metrics grid settings. - `breakdown_field` string: Field name used to split chart data into series. - `column_order` string[]: Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting. - `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. - `control_panels` KibanaHTTPAPIsKbnDiscoverSessionApiEsqlControlPanel[]: The ES|QL controls of the tab. - `config` union, required: The ES|QL control settings, including its variable, available options, and selected values. - KibanaHTTPAPIsKbnControlsSchemasOptionsListEsqlControlSchemaStaticValues: An ES|QL variable control with a fixed list of selectable options defined directly in `available_options`. - … - KibanaHTTPAPIsKbnControlsSchemasOptionsListEsqlControlSchemaValuesFromQuery: An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query. - … - `grow` boolean: When `true`, the control expands to fill any available horizontal space. - `id` string, required: The unique ID of the control. - `type` 'esql_control', required - `width` 'small' | 'medium' | 'large': The minimum width of the control. - `counter_aggregation` 'avg' | 'sum' | 'min' | 'max', required: Aggregation applied to counter metric fields. - `data_source` KibanaHTTPAPIsEsqlDataSource, required: Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields. - `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` 'esql', required - `default_rendered_nodes` number: The number of nodes each JSON cell renders by default in the JSON document view. - `density` 'compact' | 'expanded' | 'normal': The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference. - `dimensions` string[], required: Fields used to group metrics in the metrics grid. - `documents_display_mode` 'table' | 'json': How documents are shown: `table` for a formatted table or `json` for a raw JSON tree. - `esql_approximation` boolean: When `true`, ES|QL visualizations that use `STATS` run with [approximate execution](https://www.elastic.co/docs/reference/query-languages/esql/esql-query-approximation) for faster, estimated results. - `gauge_aggregation` 'avg' | 'sum' | 'min' | 'max', required: Aggregation applied to gauge metric fields. - `grid_sort_direction` 'asc' | 'desc': Direction of the metrics grid order. If omitted, defaults to ascending. - `grid_sort_field` 'alphabetically' | 'recency': 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. - `header_row_height` union: 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. - number - 'auto' - `hide_chart` boolean: 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: When `true`, the data table is hidden. - `histogram_percentile` 'p50' | 'p75' | 'p90' | 'p95' | 'p99', required: Percentile displayed for histogram metric fields. - `id` string, required: A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores. - `label` string, required: The label of the tab. - `refresh_interval` KibanaHTTPAPIsKbnDataServiceServerRefreshIntervalSchema: 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: 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. - number - '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. - `search_term` string, required: Search term used to filter metrics in the metrics grid. - `sort` object[]: Sort configuration for the data table (field and direction). - `direction` 'asc' | 'desc', required: The sort direction: `asc` for ascending or `desc` for descending. - `name` string, required: The name of the field to sort by. - `time_range` KibanaHTTPAPIsKbnEsQueryServerTimeRangeSchema: Specifies the time range for a query. - `from` string, required: The start of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now-7d`) or ISO 8601 timestamps. - `mode` union: The time range mode. Use `absolute` for fixed start and end timestamps. Use `relative` for [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions that are re-evaluated at query time (for example, `now-7d`). - 'absolute' - 'relative' - `to` string, required: The end of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now`) or ISO 8601 timestamps. - `type` 'metrics', 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. - `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` object, required: Lens visualization attributes used to render the Discover chart. - `suggestion_type` 'lensSuggestion' | 'histogramForESQL' | 'histogramForDataView', required: Chart suggestion type used by Discover to generate this histogram configuration. - `wrap_lines` boolean: When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line. - `tags` string[]: Tag IDs to associate with this Discover session. - `title` string, required: The title of the Discover session. ## Response `200` Updated - object - `data` KibanaHTTPAPIsKbnDiscoverSessionData, required: Configuration data for a Discover session. - `description` string: A short description of the Discover session. - `tabs` union[], required: Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference. - union: 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. - object - `breakdown_field` string: Field name used to split chart data into series. - `chart_interval` 'auto' | 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'y': Time interval for the chart histogram on this tab. - `column_order` string[]: Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting. - `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. - `control_panels` KibanaHTTPAPIsKbnDiscoverSessionApiEsqlControlPanel[]: The ES|QL controls of the tab. - `config` union, required: The ES|QL control settings, including its variable, available options, and selected values. - … - `grow` boolean: When `true`, the control expands to fill any available horizontal space. - `id` string, required: The unique ID of the control. - `type` 'esql_control', required - `width` 'small' | 'medium' | 'large': The minimum width of the control. - `data_source` union, required: The data view used by the tab, specified by reference or defined inline. - KibanaHTTPAPIsKbnDataViewReferenceSchema - … - KibanaHTTPAPIsKbnDataViewSpecSchema - … - `default_rendered_nodes` number: The number of nodes each JSON cell renders by default in the JSON document view. - `density` 'compact' | 'expanded' | 'normal': The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference. - `documents_display_mode` 'table' | 'json': How documents are shown: `table` for a formatted table or `json` for a raw JSON tree. - `filters` KibanaHTTPAPIsKbnAsCodeFiltersSchemaAsCodeFilterSchema[]: List of filters to apply to the data in the tab. - union: 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`). - … - `header_row_height` union: 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. - number - '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. - `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. - `id` string, required: A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores. - `label` string, required: The label of the tab. - `query` KibanaHTTPAPIsKbnAsCodeQuery: 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` 'kql' | 'lucene', required: Query language. Use `kql` for Kibana Query Language (KQL) or `lucene` for Lucene query syntax. - `refresh_interval` KibanaHTTPAPIsKbnDataServiceServerRefreshIntervalSchema: 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: 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. - number - '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. - `sample_size` number: The number of documents to sample for the data table. If omitted, defaults to the `discover:sampleSize` advanced setting. - `sort` object[]: Sort configuration for the data table (field and direction). - `direction` 'asc' | 'desc', required: The sort direction: `asc` for ascending or `desc` for descending. - `name` string, required: The name of the field to sort by. - `time_range` KibanaHTTPAPIsKbnEsQueryServerTimeRangeSchema: Specifies the time range for a query. - `from` string, required: The start of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now-7d`) or ISO 8601 timestamps. - `mode` union: The time range mode. Use `absolute` for fixed start and end timestamps. Use `relative` for [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions that are re-evaluated at query time (for example, `now-7d`). - … - `to` string, required: The end of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now`) or ISO 8601 timestamps. - `type` 'default': The tab type. `default` tabs have no type-specific settings. - `view_mode` 'documents' | 'patterns' | 'aggregated': The Discover view mode: `documents` (search hits), `patterns` (pattern analysis), or `aggregated` (field statistics). - `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` object, required: Lens visualization attributes used to render the Discover chart. - `suggestion_type` 'lensSuggestion' | 'histogramForESQL' | 'histogramForDataView', required: Chart suggestion type used by Discover to generate this histogram configuration. - `wrap_lines` boolean: When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line. - object - `breakdown_field` string: Field name used to split chart data into series. - `column_order` string[]: Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting. - `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. - `control_panels` KibanaHTTPAPIsKbnDiscoverSessionApiEsqlControlPanel[]: The ES|QL controls of the tab. - `config` union, required: The ES|QL control settings, including its variable, available options, and selected values. - … - `grow` boolean: When `true`, the control expands to fill any available horizontal space. - `id` string, required: The unique ID of the control. - `type` 'esql_control', required - `width` 'small' | 'medium' | 'large': The minimum width of the control. - `data_source` KibanaHTTPAPIsEsqlDataSource, required: Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields. - `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` 'esql', required - `default_rendered_nodes` number: The number of nodes each JSON cell renders by default in the JSON document view. - `density` 'compact' | 'expanded' | 'normal': The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference. - `documents_display_mode` 'table' | 'json': How documents are shown: `table` for a formatted table or `json` for a raw JSON tree. - `esql_approximation` boolean: When `true`, ES|QL visualizations that use `STATS` run with [approximate execution](https://www.elastic.co/docs/reference/query-languages/esql/esql-query-approximation) for faster, estimated results. - `header_row_height` union: 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. - number - 'auto' - `hide_chart` boolean: 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: When `true`, the data table is hidden. - `id` string, required: A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores. - `label` string, required: The label of the tab. - `refresh_interval` KibanaHTTPAPIsKbnDataServiceServerRefreshIntervalSchema: 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: 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. - number - '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. - `sort` object[]: Sort configuration for the data table (field and direction). - `direction` 'asc' | 'desc', required: The sort direction: `asc` for ascending or `desc` for descending. - `name` string, required: The name of the field to sort by. - `time_range` KibanaHTTPAPIsKbnEsQueryServerTimeRangeSchema: Specifies the time range for a query. - `from` string, required: The start of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now-7d`) or ISO 8601 timestamps. - `mode` union: The time range mode. Use `absolute` for fixed start and end timestamps. Use `relative` for [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions that are re-evaluated at query time (for example, `now-7d`). - … - `to` string, required: The end of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now`) or ISO 8601 timestamps. - `type` 'default': The tab type. `default` tabs have no type-specific settings. - `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` object, required: Lens visualization attributes used to render the Discover chart. - `suggestion_type` 'lensSuggestion' | 'histogramForESQL' | 'histogramForDataView', required: Chart suggestion type used by Discover to generate this histogram configuration. - `wrap_lines` boolean: When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line. - object: An ES|QL tab with saved metrics grid settings. - `breakdown_field` string: Field name used to split chart data into series. - `column_order` string[]: Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting. - `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. - `control_panels` KibanaHTTPAPIsKbnDiscoverSessionApiEsqlControlPanel[]: The ES|QL controls of the tab. - `config` union, required: The ES|QL control settings, including its variable, available options, and selected values. - … - `grow` boolean: When `true`, the control expands to fill any available horizontal space. - `id` string, required: The unique ID of the control. - `type` 'esql_control', required - `width` 'small' | 'medium' | 'large': The minimum width of the control. - `counter_aggregation` 'avg' | 'sum' | 'min' | 'max', required: Aggregation applied to counter metric fields. - `data_source` KibanaHTTPAPIsEsqlDataSource, required: Uses an ES|QL query as the data source. The query is executed at render time; resulting columns are available as fields. - `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` 'esql', required - `default_rendered_nodes` number: The number of nodes each JSON cell renders by default in the JSON document view. - `density` 'compact' | 'expanded' | 'normal': The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference. - `dimensions` string[], required: Fields used to group metrics in the metrics grid. - `documents_display_mode` 'table' | 'json': How documents are shown: `table` for a formatted table or `json` for a raw JSON tree. - `esql_approximation` boolean: When `true`, ES|QL visualizations that use `STATS` run with [approximate execution](https://www.elastic.co/docs/reference/query-languages/esql/esql-query-approximation) for faster, estimated results. - `gauge_aggregation` 'avg' | 'sum' | 'min' | 'max', required: Aggregation applied to gauge metric fields. - `grid_sort_direction` 'asc' | 'desc': Direction of the metrics grid order. If omitted, defaults to ascending. - `grid_sort_field` 'alphabetically' | 'recency': 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. - `header_row_height` union: 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. - number - 'auto' - `hide_chart` boolean: 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: When `true`, the data table is hidden. - `histogram_percentile` 'p50' | 'p75' | 'p90' | 'p95' | 'p99', required: Percentile displayed for histogram metric fields. - `id` string, required: A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores. - `label` string, required: The label of the tab. - `refresh_interval` KibanaHTTPAPIsKbnDataServiceServerRefreshIntervalSchema: 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: 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. - number - '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. - `search_term` string, required: Search term used to filter metrics in the metrics grid. - `sort` object[]: Sort configuration for the data table (field and direction). - `direction` 'asc' | 'desc', required: The sort direction: `asc` for ascending or `desc` for descending. - `name` string, required: The name of the field to sort by. - `time_range` KibanaHTTPAPIsKbnEsQueryServerTimeRangeSchema: Specifies the time range for a query. - `from` string, required: The start of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now-7d`) or ISO 8601 timestamps. - `mode` union: The time range mode. Use `absolute` for fixed start and end timestamps. Use `relative` for [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions that are re-evaluated at query time (for example, `now-7d`). - … - `to` string, required: The end of the time range. Accepts Elasticsearch [date math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math) expressions (for example, `now`) or ISO 8601 timestamps. - `type` 'metrics', 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. - `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` object, required: Lens visualization attributes used to render the Discover chart. - `suggestion_type` 'lensSuggestion' | 'histogramForESQL' | 'histogramForDataView', required: Chart suggestion type used by Discover to generate this histogram configuration. - `wrap_lines` boolean: When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line. - `tags` string[]: Tag IDs to associate with this Discover session. - `title` string, required: The title of the Discover session. - `id` string, required: The Discover session ID. - `meta` KibanaHTTPAPIsKbnAsCodeMeta, 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. ## Other responses - `201`: Created - `400`: Invalid request - `403`: Forbidden - `409`: Conflict --- [API](https://skmtc.dev/elastic/apis/kibana-apis.md) - [All operations](https://skmtc.dev/elastic/apis/kibana-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/elastic/apis/kibana-apis/revisions/b87131d80c52?raw)