You're viewing version 3.5 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Query Insights Settings API

Introduced 3.5

The Query Insights Settings API allows you to manage query insights configuration through dedicated endpoints. Use this API to configure top N query monitoring, grouping, and exporter settings with granular, setting-level access control.

This API is functionally equivalent to the Cluster Settings API for query insights configuration. For production environments, you can use the dedicated permission cluster:admin/opensearch/insights/settings/* to grant performance engineers or monitoring teams access only to query insights settings, without exposing all cluster settings.

The API provides the following endpoints:

• Retrieve settings
• Update settings

Retrieve query insights settings

Retrieves all query insights settings, including latency, CPU, memory, grouping, and exporter configurations.

Endpoints

GET /_insights/settings
GET /_insights/settings/{metric_type}

Path parameters

The following table lists the available path parameters. All path parameters are optional.

Example request

GET /_insights/settings/

Example response

{
  "persistent": {
    "latency": {
      "enabled": true,
      "top_n_size": 10,
      "window_size": "5m"
    },
    "cpu": {
      "enabled": true,
      "top_n_size": 10,
      "window_size": "5m"
    },
    "memory": {
      "enabled": true,
      "top_n_size": 10,
      "window_size": "5m"
    },
    "grouping": {
      "group_by": "none"
    },
    "exporter": {
      "type": "local_index",
      "delete_after_days": 7
    }
  }
}

Response body fields

The following table lists all response body fields.

Update query insights settings

Updates query insights settings. You can update settings for one or more metrics in a single request.

Endpoint

PUT /_insights/settings

Request body fields

The following table lists the available request body fields.

For more information about metric settings, see Top N queries.

For more information about query grouping, see Grouping top N queries.

For more information about exporters, see Exporting top N query data.

Example request: Updating latency settings

PUT /_insights/settings
{
  "latency": {
    "enabled": true,
    "top_n_size": 20,
    "window_size": "10m"
  }
}

Example request: Updating multiple metric settings

PUT /_insights/settings
{
  "latency": {
    "enabled": true,
    "top_n_size": 15
  },
  "cpu": {
    "enabled": true,
    "top_n_size": 10,
    "window_size": "10m"
  },
  "memory": {
    "enabled": false
  }
}

Example request: Updating grouping settings

PUT /_insights/settings
{
  "grouping": {
    "group_by": "similarity"
  }
}

Example request: Updating exporter settings

PUT /_insights/settings
{
  "exporter": {
    "type": "local_index",
    "delete_after_days": 7
  }
}

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions:

• cluster:admin/opensearch/insights/settings/get for GET requests
• cluster:admin/opensearch/insights/settings/update for PUT requests
• cluster:admin/opensearch/insights/settings/* for all query insights settings API operations

You can configure these permissions in your Security plugin or access control system.

For production deployments, consider creating a dedicated role with access only to these endpoints rather than granting full cluster settings permissions.

Related documentation

• Top N queries
• Grouping top N queries
• Query Insights dashboard
• Cluster settings API