---
type: api
title: Create a Discover session
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/kibana/v9/operation/operation-create-discover-session
resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/kibana/v9/operation/operation-create-discover-session
products:
  - Kibana
---

# Create a Discover session

Authentication: required

Availability: Planned

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/discover_sessions`
- `POST` `/s/{space_id}/api/discover_sessions`

#### Path parameters

- `space_id` (string) — optional
  An identifier for the space. If `space_id` is not provided in the URL, the default space is used. Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

## Description

Creates a Discover session and returns its ID, full state, and metadata.

## Header parameters

- `kbn-xsrf` (string) — required
  A required header to protect against CSRF attacks

## Request body

`application/json`

- `description` (string · max length: 10000) — optional
  A short description of the Discover session.
- `tabs` (union anyOf[] · min items: 1 · max items: 25) — required
  Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference.
  - **header_row_height: auto**
    - `breakdown_field` (string · max length: 1000) — optional
      Field name used to split chart data into series.
    - `chart_interval` (enum) — optional
      Time interval for the chart histogram on this tab.
      Values: `auto`, `ms`, `s`, `m`, `h`, `d`, `w`, `M`, `y`
    - `column_order` (string[] · max items: 100) — optional
      Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting.
    - `column_settings` (map string to object) — optional
      Per-column settings keyed by field name, such as width. Keys should correspond to entries in `column_order` when both are set.
      Map values (object)
      - `width` (number · min: 0) — optional
        Optional width of the column in pixels.
    - `control_panels` (object[] · max items: 1000) — optional
      The ES|QL controls of the tab.
      - `config` (union oneOf) — required
        The ES|QL control settings, including its variable, available options, and selected values.
        - **STATIC_VALUES** (`control_type: STATIC_VALUES`)
          An ES|QL variable control with a fixed list of selectable options defined directly in `available_options`.
          - `control_type` (enum) — required
            Values: `STATIC_VALUES`
          - `available_options` (string[] · max items: 1000) — required
            A fixed list of option strings displayed in the control.
          - `display_settings` (object) — optional
            - `hide_action_bar` (boolean) — optional
              When `true`, the search bar, sorting options, and select all toggle are hidden from the control.
            - `hide_exclude` (boolean) — optional
              When `true`, the exclude mode toggle is hidden from the control.
            - `hide_exists` (boolean) — optional
              When `true`, the exists filter option is hidden from the control.
            - `hide_sort` (boolean) — optional
              When `true`, the sort selector is hidden from the control.
            - `placeholder` (string) — optional
              Placeholder text displayed in the control input when no option is selected.
          - `selected_options` (string[] · max items: 10000) — required
            The list of currently selected option values.
          - `single_select` (boolean · default: true) — optional
            When `true`, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to `true`.
          - `title` (string) — optional
            A human-readable title for the control.
          - `variable_name` (string) — required
            The name of the ES|QL variable that this control populates. The variable is referenced in ES|QL queries using the `?variable_name` syntax.
          - `variable_type` (enum) — required
            The ES|QL variable type that determines how the selected value is substituted into the query. Accepts `fields`, `values`, `functions`, `time_literal`, or `multi_values`.
            Values: `fields`, `values`, `functions`, `time_literal`, `multi_values`
        - **VALUES_FROM_QUERY** (`control_type: VALUES_FROM_QUERY`)
          An ES|QL variable control whose selectable options are dynamically retrieved by running an ES|QL query.
          - `control_type` (enum) — required
            Values: `VALUES_FROM_QUERY`
          - `display_settings` (object) — optional
            - `hide_action_bar` (boolean) — optional
              When `true`, the search bar, sorting options, and select all toggle are hidden from the control.
            - `hide_exclude` (boolean) — optional
              When `true`, the exclude mode toggle is hidden from the control.
            - `hide_exists` (boolean) — optional
              When `true`, the exists filter option is hidden from the control.
            - `hide_sort` (boolean) — optional
              When `true`, the sort selector is hidden from the control.
            - `placeholder` (string) — optional
              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` (string[] · max items: 10000) — required
            The list of currently selected option values.
          - `single_select` (boolean · default: true) — optional
            When `true`, only one option can be selected at a time. Selecting a new option deselects any previously selected option. Defaults to `true`.
          - `title` (string) — optional
            A human-readable title for the control.
          - `variable_name` (string) — required
            The name of the ES|QL variable that this control populates. The variable is referenced in ES|QL queries using the `?variable_name` syntax.
          - `variable_type` (enum) — required
            The ES|QL variable type that determines how the selected value is substituted into the query. Accepts `fields`, `values`, `functions`, `time_literal`, or `multi_values`.
            Values: `fields`, `values`, `functions`, `time_literal`, `multi_values`
      - `grow` (boolean · default: false) — optional
        When `true`, the control expands to fill any available horizontal space.
      - `id` (string · min length: 1) — required
        The unique ID of the control.
      - `type` (enum) — required
        Values: `esql_control`
      - `width` (enum · default: medium) — optional
        The minimum width of the control.
        Values: `small`, `medium`, `large`
    - `data_source` (union oneOf) — required
      The data view used by the tab, specified by reference or defined inline.
      - **Data view reference** (`type: data_view_reference`)
        - `type` (enum) — required
          Values: `data_view_reference`
        - `ref_id` (string) — required
          The id of the Kibana data view to use as the data source. Example: "my-data-view".
      - **Data view inline spec** (`type: data_view_spec`)
        - `type` (enum) — required
          Values: `data_view_spec`
        - `allow_hidden_indices` (boolean) — optional
          When `true`, allows the data view to match hidden indices.
        - `field_filters` (string[] · max items: 10000) — optional
          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` (map string to anyOf) — optional
          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 · min length: 1) — required
          The index pattern (Elasticsearch index expression) to use as the data source. Example: "my-index-*".
        - `name` (string · min length: 1 · max length: 256) — optional
          The name of the data view. Example: "Sample data view".
        - `time_field` (string) — optional
          The name of the time field in the index. Used for time-based filtering. Example: "@timestamp".
    - `default_rendered_nodes` (number · min: 10 · max: 200) — optional
      The number of nodes each JSON cell renders by default in the JSON document view.
    - `density` (enum) — optional
      The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
      Values: `compact`, `expanded`, `normal`
    - `documents_display_mode` (enum) — optional
      How documents are shown: `table` for a formatted table or `json` for a raw JSON tree.
      Values: `table`, `json`
    - `filters` (union oneOf[] · max items: 100 · default: []) — optional
      List of filters to apply to the data in the tab.
      - **condition**
        A filter that evaluates a single field condition such as equality, range, or existence.
        - `type` (enum) — required
          Values: `condition`
        - `condition` (union oneOf) — required
          A filter condition with strict operator/value type matching.
          - **is** (`operator: is`)
            Matches documents where `field` equals a single specified value.
            - `operator` (enum) — required
              Values: `is`
            - `field` (string) — required
              Name of the document field the condition evaluates.
            - `negate` (boolean) — optional
              When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
            - `value` (union string | number | boolean) — required
              Single value to compare against the field.
          - **is_one_of** (`operator: is_one_of`)
            Matches documents where `field` equals any value in a provided list.
            - `operator` (enum) — required
              Values: `is_one_of`
            - `field` (string) — required
              Name of the document field the condition evaluates.
            - `negate` (boolean) — optional
              When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
            - `value` (union string[] | number[] | boolean[]) — required
              Homogeneous array of values to match against the field.
          - **range** (`operator: range`)
            Matches documents where `field` falls within a specified numeric or date range.
            - `operator` (enum) — required
              Values: `range`
            - `field` (string) — required
              Name of the document field the condition evaluates.
            - `negate` (boolean) — optional
              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.
              - `format` (string) — optional
                Elasticsearch [date format](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/mapping-date-format) string applied when parsing date boundary values. For example, `strict_date_optional_time` or `epoch_millis`.
              - `gt` (number | string) — optional
                Greater than.
              - `gte` (number | string) — optional
                Greater than or equal to.
              - `lt` (number | string) — optional
                Less than.
              - `lte` (number | string) — optional
                Less than or equal to.
          - **exists** (`operator: exists`)
            Matches documents where `field` exists and contains a non-null value.
            - `operator` (enum) — required
              Values: `exists`
            - `field` (string) — required
              Name of the document field the condition evaluates.
            - `negate` (boolean) — optional
              When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
        - `controlled_by` (string) — optional
          Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.
        - `data_view_id` (string) — optional
          Identifier of the data view used as context for this filter.
        - `disabled` (boolean) — optional
          When `true`, the filter is inactive and does not affect query results. Defaults to `false`.
        - `is_multi_index` (boolean) — optional
          When `true`, the filter can be applied across multiple indices. Defaults to `false`.
        - `label` (string) — optional
          Human-readable label for the filter, used for display purposes.
        - `negate` (boolean) — optional
          When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
      - **group**
        A filter that combines multiple conditions or nested groups using a logical `and` or `or` operator.
        - `type` (enum) — required
          Values: `group`
        - `controlled_by` (string) — optional
          Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.
        - `data_view_id` (string) — optional
          Identifier of the data view used as context for this filter.
        - `disabled` (boolean) — optional
          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.
          - `conditions` (union anyOf[]) — required — recursive
            Ordered list of conditions or nested groups combined by the group `operator`.
          - `operator` (enum) — required
            Logical operator applied across all entries in `conditions`. Use `and` to require all conditions, or `or` to require at least one.
            Values: `and`, `or`
        - `is_multi_index` (boolean) — optional
          When `true`, the filter can be applied across multiple indices. Defaults to `false`.
        - `label` (string) — optional
          Human-readable label for the filter, used for display purposes.
        - `negate` (boolean) — optional
          When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
      - **dsl**
        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.
        - `type` (enum) — required
          Values: `dsl`
        - `controlled_by` (string) — optional
          Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.
        - `data_view_id` (string) — optional
          Identifier of the data view used as context for this filter.
        - `disabled` (boolean) — optional
          When `true`, the filter is inactive and does not affect query results. Defaults to `false`.
        - `dsl` (map string to object) — required
          Elasticsearch Query DSL object passed directly to the query.
        - `field` (string) — optional
          Field name for scripted filters where the field cannot be extracted from the DSL query.
        - `is_multi_index` (boolean) — optional
          When `true`, the filter can be applied across multiple indices. Defaults to `false`.
        - `label` (string) — optional
          Human-readable label for the filter, used for display purposes.
        - `negate` (boolean) — optional
          When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
        - `params` (object) — optional
          Filter parameters metadata. May contain display values, formats, and parameters for scripted filters.
      - **spatial**
        A filter that applies an Elasticsearch geo query, used for geographic boundary and shape matching.
        - `type` (enum) — required
          Values: `spatial`
        - `controlled_by` (string) — optional
          Identifier of the panel that manages this filter. When set, the filter is treated as owned by that panel.
        - `data_view_id` (string) — optional
          Identifier of the data view used as context for this filter.
        - `disabled` (boolean) — optional
          When `true`, the filter is inactive and does not affect query results. Defaults to `false`.
        - `dsl` (map string to object) — required
          Elasticsearch geo query DSL object.
        - `is_multi_index` (boolean) — optional
          When `true`, the filter can be applied across multiple indices. Defaults to `false`.
        - `label` (string) — optional
          Human-readable label for the filter, used for display purposes.
        - `negate` (boolean) — optional
          When `true`, the filter is negated and matches documents that do NOT satisfy the condition. Defaults to `false`.
    - `header_row_height` (union number | enum) — optional
      The table header row height, as a number of lines, or `auto` to size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference.
      Values: `auto`
    - `hide_aggregated_preview` (boolean) — optional
      Applies to the field statistics view. When `true`, hides the distribution preview shown for each field. If omitted, previews are shown.
    - `hide_chart` (boolean · default: false) — optional
      When `true`, the chart is hidden.
    - `hide_nulls` (boolean) — optional
      When `true`, fields with null values are hidden in the JSON document view.
    - `hide_table` (boolean · default: false) — optional
      When `true`, the data table is hidden.
    - `id` (string · min length: 1 · max length: 250) — required
      A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
    - `label` (string · max length: 120) — required
      The label of the tab.
    - `query` (object) — optional
      A search query consisting of an expression and its language. Supports KQL and Lucene syntax.
      - `expression` (string) — required
        A query expression in KQL or Lucene syntax.
      - `language` (enum) — required
        Query language. Use `kql` for Kibana Query Language (KQL) or `lucene` for Lucene query syntax.
        Values: `kql`, `lucene`
    - `refresh_interval` (object) — optional
      Specifies the auto-refresh interval for the object.
      - `pause` (boolean) — required
        When `true`, auto-refresh is paused.
      - `value` (number) — required
        The refresh interval in milliseconds.
    - `row_height` (union number | enum) — optional
      The table data row height, as a number of lines, or `auto` to size it based on content. If omitted, defaults to the `discover:rowHeightOption` advanced setting.
      Values: `auto`
    - `rows_per_page` (number · min: 1 · max: 10000) — optional
      The number of rows to display per page in the data table. If omitted, defaults to the `discover:sampleRowsPerPage` advanced setting. Has no effect on ES|QL tabs.
    - `sample_size` (number · min: 10 · max: 10000) — optional
      The number of documents to sample for the data table. If omitted, defaults to the `discover:sampleSize` advanced setting.
    - `sort` (object[] · max items: 100 · default: []) — optional
      Sort configuration for the data table (field and direction).
      - `direction` (enum) — required
        The sort direction: `asc` for ascending or `desc` for descending.
        Values: `asc`, `desc`
      - `name` (string) — required
        The name of the field to sort by.
    - `time_range` (object) — optional
      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` (enum) — optional
        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`).
        Values: `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` (enum · default: default) — optional
      The tab type. `default` tabs have no type-specific settings.
      Values: `default`
    - `view_mode` (enum · default: documents) — optional
      The Discover view mode: `documents` (search hits), `patterns` (pattern analysis), or `aggregated` (field statistics).
      Values: `documents`, `patterns`, `aggregated`
    - `vis_context` (object) — optional
      The saved chart configuration. Discover reuses it when compatible with the tab’s current settings and query results; otherwise, it rebuilds the chart.
      - `attributes` (map string to object) — required
        Lens visualization attributes used to render the Discover chart.
      - `suggestion_type` (enum) — required
        Chart suggestion type used by Discover to generate this histogram configuration.
        Values: `lensSuggestion`, `histogramForESQL`, `histogramForDataView`
    - `wrap_lines` (boolean) — optional
      When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line.
  - **header_row_height: auto**
    - `breakdown_field` (string · max length: 1000) — optional
      Field name used to split chart data into series.
    - `column_order` (string[] · max items: 100) — optional
      Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting.
    - `column_settings` (map string to object) — optional
      Per-column settings keyed by field name, such as width. Keys should correspond to entries in `column_order` when both are set.
      Map values (object)
      - `width` (number · min: 0) — optional
        Optional width of the column in pixels.
    - `control_panels` (object[] · max items: 1000) — optional
      The ES|QL controls of the tab.
      Same fields as `control_panels` in `header_row_height: auto`
    - `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.
      - `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` (enum) — required
        Values: `esql`
    - `default_rendered_nodes` (number · min: 10 · max: 200) — optional
      The number of nodes each JSON cell renders by default in the JSON document view.
    - `density` (enum) — optional
      The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
      Values: `compact`, `expanded`, `normal`
    - `documents_display_mode` (enum) — optional
      How documents are shown: `table` for a formatted table or `json` for a raw JSON tree.
      Values: `table`, `json`
    - `esql_approximation` (boolean) — optional
      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 number | enum) — optional
      The table header row height, as a number of lines, or `auto` to size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference.
      Values: `auto`
    - `hide_chart` (boolean · default: false) — optional
      When `true`, the chart is hidden.
    - `hide_nulls` (boolean) — optional
      When `true`, fields with null values are hidden in the JSON document view.
    - `hide_table` (boolean · default: false) — optional
      When `true`, the data table is hidden.
    - `id` (string · min length: 1 · max length: 250) — required
      A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
    - `label` (string · max length: 120) — required
      The label of the tab.
    - `refresh_interval` (object) — optional
      Specifies the auto-refresh interval for the object.
      - `pause` (boolean) — required
        When `true`, auto-refresh is paused.
      - `value` (number) — required
        The refresh interval in milliseconds.
    - `row_height` (union number | enum) — optional
      The table data row height, as a number of lines, or `auto` to size it based on content. If omitted, defaults to the `discover:rowHeightOption` advanced setting.
      Values: `auto`
    - `rows_per_page` (number · min: 1 · max: 10000) — optional
      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[] · max items: 100 · default: []) — optional
      Sort configuration for the data table (field and direction).
      - `direction` (enum) — required
        The sort direction: `asc` for ascending or `desc` for descending.
        Values: `asc`, `desc`
      - `name` (string) — required
        The name of the field to sort by.
    - `time_range` (object) — optional
      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` (enum) — optional
        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`).
        Values: `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` (enum · default: default) — optional
      The tab type. `default` tabs have no type-specific settings.
      Values: `default`
    - `vis_context` (object) — optional
      The saved chart configuration. Discover reuses it when compatible with the tab’s current settings and query results; otherwise, it rebuilds the chart.
      - `attributes` (map string to object) — required
        Lens visualization attributes used to render the Discover chart.
      - `suggestion_type` (enum) — required
        Chart suggestion type used by Discover to generate this histogram configuration.
        Values: `lensSuggestion`, `histogramForESQL`, `histogramForDataView`
    - `wrap_lines` (boolean) — optional
      When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line.
  - **Metrics tab**
    An ES|QL tab with saved metrics grid settings.
    - `breakdown_field` (string · max length: 1000) — optional
      Field name used to split chart data into series.
    - `column_order` (string[] · max items: 100) — optional
      Ordered list of field names to display in the data table. If omitted, defaults to the `defaultColumns` advanced setting.
    - `column_settings` (map string to object) — optional
      Per-column settings keyed by field name, such as width. Keys should correspond to entries in `column_order` when both are set.
      Map values (object)
      - `width` (number · min: 0) — optional
        Optional width of the column in pixels.
    - `control_panels` (object[] · max items: 1000) — optional
      The ES|QL controls of the tab.
      Same fields as `control_panels` in `header_row_height: auto`
    - `counter_aggregation` (enum) — required
      Aggregation applied to counter metric fields.
      Values: `avg`, `sum`, `min`, `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.
      - `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` (enum) — required
        Values: `esql`
    - `default_rendered_nodes` (number · min: 10 · max: 200) — optional
      The number of nodes each JSON cell renders by default in the JSON document view.
    - `density` (enum) — optional
      The table row spacing. If omitted, Kibana determines the density from its current settings, such as the user preference.
      Values: `compact`, `expanded`, `normal`
    - `dimensions` (string[] · max items: 5) — required
      Fields used to group metrics in the metrics grid.
    - `documents_display_mode` (enum) — optional
      How documents are shown: `table` for a formatted table or `json` for a raw JSON tree.
      Values: `table`, `json`
    - `esql_approximation` (boolean) — optional
      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` (enum) — required
      Aggregation applied to gauge metric fields.
      Values: `avg`, `sum`, `min`, `max`
    - `grid_sort_direction` (enum) — optional
      Direction of the metrics grid order. If omitted, defaults to ascending.
      Values: `asc`, `desc`
    - `grid_sort_field` (enum) — optional
      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: `alphabetically`, `recency`
    - `header_row_height` (union number | enum) — optional
      The table header row height, as a number of lines, or `auto` to size it based on content. If omitted, Kibana determines the height from its current settings, such as the user preference.
      Values: `auto`
    - `hide_chart` (boolean · default: false) — optional
      When `true`, the chart is hidden.
    - `hide_nulls` (boolean) — optional
      When `true`, fields with null values are hidden in the JSON document view.
    - `hide_table` (boolean · default: false) — optional
      When `true`, the data table is hidden.
    - `histogram_percentile` (enum) — required
      Percentile displayed for histogram metric fields.
      Values: `p50`, `p75`, `p90`, `p95`, `p99`
    - `id` (string · min length: 1 · max length: 250) — required
      A unique identifier. Must contain only lowercase letters, numbers, hyphens, and underscores.
    - `label` (string · max length: 120) — required
      The label of the tab.
    - `refresh_interval` (object) — optional
      Specifies the auto-refresh interval for the object.
      - `pause` (boolean) — required
        When `true`, auto-refresh is paused.
      - `value` (number) — required
        The refresh interval in milliseconds.
    - `row_height` (union number | enum) — optional
      The table data row height, as a number of lines, or `auto` to size it based on content. If omitted, defaults to the `discover:rowHeightOption` advanced setting.
      Values: `auto`
    - `rows_per_page` (number · min: 1 · max: 10000) — optional
      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 · max length: 1000) — required
      Search term used to filter metrics in the metrics grid.
    - `sort` (object[] · max items: 100 · default: []) — optional
      Sort configuration for the data table (field and direction).
      - `direction` (enum) — required
        The sort direction: `asc` for ascending or `desc` for descending.
        Values: `asc`, `desc`
      - `name` (string) — required
        The name of the field to sort by.
    - `time_range` (object) — optional
      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` (enum) — optional
        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`).
        Values: `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` (enum) — 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.
      Values: `metrics`
    - `vis_context` (object) — optional
      The saved chart configuration. Discover reuses it when compatible with the tab’s current settings and query results; otherwise, it rebuilds the chart.
      - `attributes` (map string to object) — required
        Lens visualization attributes used to render the Discover chart.
      - `suggestion_type` (enum) — required
        Chart suggestion type used by Discover to generate this histogram configuration.
        Values: `lensSuggestion`, `histogramForESQL`, `histogramForDataView`
    - `wrap_lines` (boolean) — optional
      When `true`, long values wrap in the JSON document view. When `false`, they are truncated to a single line.
- `tags` (string[] · max items: 1000 · default: []) — optional
  Tag IDs to associate with this Discover session.
- `title` (string · min length: 1 · max length: 1000) — required
  The title of the Discover session.

## Responses

#### `201`

Created

`application/json`

- `data` (object)
  Configuration data for a Discover session.
  - `description` (string · max length: 10000)
    A short description of the Discover session.
  - `tabs` (union anyOf[] · min items: 1 · max items: 25)
    Ordered list of tabs in the Discover session. Each tab requires a stable, unique ID, which other saved objects and links can reference.
    Same options as `tabs`
  - `tags` (string[] · max items: 1000 · default: [])
    Tag IDs to associate with this Discover session.
  - `title` (string · min length: 1 · max length: 1000)
    The title of the Discover session.
- `id` (string)
  The Discover session ID.
- `meta` (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.
#### `400`

Invalid request

#### `403`

Forbidden

## Code examples

#### Console

```console
POST kbn:/api/discover_sessions
{
  "title": "Requests by extension",
  "description": "",
  "tags": [],
  "tabs": [
    {
      "id": "requests",
      "label": "Requests",
      "type": "default",
      "data_source": {
        "type": "esql",
        "query": "FROM kibana_sample_data_logs | STATS requests = COUNT(*) BY extension | SORT requests DESC"
      },
      "column_order": [
        "extension",
        "requests"
      ],
      "sort": [],
      "hide_chart": false,
      "hide_table": false
    }
  ]
}
```

#### curl

```curl
curl -X POST "${KIBANA_URL}/api/discover_sessions" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "elastic-api-version: 2023-10-31" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Requests by extension",
  "description": "",
  "tags": [],
  "tabs": [
    {
      "id": "requests",
      "label": "Requests",
      "type": "default",
      "data_source": {
        "type": "esql",
        "query": "FROM kibana_sample_data_logs | STATS requests = COUNT(*) BY extension | SORT requests DESC"
      },
      "column_order": [
        "extension",
        "requests"
      ],
      "sort": [],
      "hide_chart": false,
      "hide_table": false
    }
  ]
}'
```

## Response examples

#### Response for the ES|QL session example

`application/json`

```json
{
  "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="
  }
}
```