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