Clarify metrics API query strings (DataDog#3269)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -107944,6 +107944,8 @@ paths:
     get:
       description: |-
         Get a list of actively reporting metrics for your organization. Pagination is optional using the `page[cursor]` and `page[size]` query parameters.
+
+        Query parameters use bracket notation (for example, `filter[tags]`, `filter[queried][window][seconds]`). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: `GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500`.
       operationId: ListTagConfigurations
       parameters:
         - description: Only return custom metrics that have been configured with Metrics Without Limits.
@@ -107983,7 +107985,7 @@ paths:
           schema:
             type: boolean
         - description: |-
-            Only return metrics that have been queried or not queried in the specified window. Dependent on being sent with `filter[queried]`. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second.
+            This parameter has no effect unless `filter[queried]` is also set. Only return metrics that have been queried or not queried in the specified window. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second. For example: `filter[queried]=true&filter[queried][window][seconds]=604800`.
           example: 15552000
           in: query
           name: filter[queried][window][seconds]
@@ -107995,7 +107997,7 @@ paths:
             minimum: 1
             type: integer
         - description: |-
-            Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards (for example, service:web*).
+            Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: `filter[tags]=env IN (staging,test) AND service:web*`.
           example: "env IN (staging,test) AND service:web*"
           in: query
           name: filter[tags]
@@ -108022,7 +108024,8 @@ paths:
             maximum: 2592000
             minimum: 1
             type: integer
-        - description: Maximum number of results per page. Use with `page[cursor]` for pagination. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
+        - description: |-
+            Maximum number of results per page. Send `page[size]` on the first request to opt in to pagination. On each subsequent request, send `page[cursor]` set to the value of `meta.pagination.next_cursor` from the previous response. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
           in: query
           name: page[size]
           required: false
@@ -108426,7 +108429,8 @@ paths:
       operationId: EstimateMetricsOutputSeries
       parameters:
         - $ref: "#/components/parameters/MetricName"
-        - description: Filtered tag keys that the metric is configured to query with.
+        - description: |-
+            Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`.
           example: "app,host"
           in: query
           name: filter[groups]

lib/datadog_api_client/v2/api/metrics_api.rb

@@ -323,7 +323,7 @@ def estimate_metrics_output_series(metric_name, opts = {})
     #
     # @param metric_name [String] The name of the metric.
     # @param opts [Hash] the optional parameters
-    # @option opts [String] :filter_groups Filtered tag keys that the metric is configured to query with.
+    # @option opts [String] :filter_groups Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`.
     # @option opts [Integer] :filter_hours_ago The number of hours of look back (from now) to estimate cardinality with. If unspecified, it defaults to 0 hours.
     # @option opts [Integer] :filter_num_aggregations Deprecated. Number of aggregations has no impact on volume.
     # @option opts [Boolean] :filter_pct A boolean, for distribution metrics only, to estimate cardinality if the metric includes additional percentile aggregators.
@@ -670,17 +670,19 @@ def list_tag_configurations(opts = {})
     #
     # Get a list of actively reporting metrics for your organization. Pagination is optional using the `page[cursor]` and `page[size]` query parameters.
     #
+    # Query parameters use bracket notation (for example, `filter[tags]`, `filter[queried][window][seconds]`). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: `GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500`.
+    #
     # @param opts [Hash] the optional parameters
     # @option opts [Boolean] :filter_configured Only return custom metrics that have been configured with Metrics Without Limits.
     # @option opts [String] :filter_tags_configured Only return metrics that have the given tag key(s) in their Metrics Without Limits configuration (included or excluded).
     # @option opts [MetricTagConfigurationMetricTypeCategory] :filter_metric_type Only return metrics of the given metric type.
     # @option opts [Boolean] :filter_include_percentiles Only return distribution metrics that have percentile aggregations enabled (true) or disabled (false).
     # @option opts [Boolean] :filter_queried Only return metrics that have been queried (true) or not queried (false) in the look back window. Set the window with `filter[queried][window][seconds]`; if omitted, a default window is used.
-    # @option opts [Integer] :filter_queried_window_seconds Only return metrics that have been queried or not queried in the specified window. Dependent on being sent with `filter[queried]`. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second.
-    # @option opts [String] :filter_tags Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards (for example, service:web*).
+    # @option opts [Integer] :filter_queried_window_seconds This parameter has no effect unless `filter[queried]` is also set. Only return metrics that have been queried or not queried in the specified window. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second. For example: `filter[queried]=true&filter[queried][window][seconds]=604800`.
+    # @option opts [String] :filter_tags Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: `filter[tags]=env IN (staging,test) AND service:web*`.
     # @option opts [Boolean] :filter_related_assets Only return metrics that are used in at least one dashboard, monitor, notebook, or SLO.
     # @option opts [Integer] :window_seconds Only return metrics that have been actively reporting in the specified window. The default value is 3600 seconds (1 hour), the maximum value is 2,592,000 seconds (30 days), and the minimum value is 1 second.
-    # @option opts [Integer] :page_size Maximum number of results per page. Use with `page[cursor]` for pagination. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
+    # @option opts [Integer] :page_size Maximum number of results per page. Send `page[size]` on the first request to opt in to pagination. On each subsequent request, send `page[cursor]` set to the value of `meta.pagination.next_cursor` from the previous response. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
     # @option opts [String] :page_cursor Cursor for pagination. Use `page[size]` to opt-in to pagination and get the first page; for subsequent pages, use the value from `meta.pagination.next_cursor` in the response. Pagination is complete when `next_cursor` is null.
     # @return [Array<(MetricsAndMetricTagConfigurationsResponse, Integer, Hash)>] MetricsAndMetricTagConfigurationsResponse data, response status code and response headers
     def list_tag_configurations_with_http_info(opts = {})