Clarify metrics API query strings (#3772)

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]

src/main/java/com/datadog/api/client/v2/api/MetricsApi.java

@@ -674,7 +674,8 @@ public static class EstimateMetricsOutputSeriesOptionalParameters {
     /**
      * Set filterGroups.
      *
-     * @param filterGroups Filtered tag keys that the metric is configured to query with. (optional)
+     * @param filterGroups Comma-separated list of tag keys that the metric is configured to query
+     *     with. For example: <code>filter[groups]=app,host</code>. (optional)
      * @return EstimateMetricsOutputSeriesOptionalParameters
      */
     public EstimateMetricsOutputSeriesOptionalParameters filterGroups(String filterGroups) {
@@ -1670,10 +1671,12 @@ public ListTagConfigurationsOptionalParameters filterQueried(Boolean filterQueri
     /**
      * Set filterQueriedWindowSeconds.
      *
-     * @param filterQueriedWindowSeconds Only return metrics that have been queried or not queried
-     *     in the specified window. Dependent on being sent with <code>filter[queried]</code>. 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. (optional, default to 2592000)
+     * @param filterQueriedWindowSeconds This parameter has no effect unless <code>filter[queried]
+     *     </code> 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: <code>
+     *     filter[queried]=true&amp;filter[queried][window][seconds]=604800</code>. (optional,
+     *     default to 2592000)
      * @return ListTagConfigurationsOptionalParameters
      */
     public ListTagConfigurationsOptionalParameters filterQueriedWindowSeconds(
@@ -1686,7 +1689,8 @@ public ListTagConfigurationsOptionalParameters filterQueriedWindowSeconds(
      * Set filterTags.
      *
      * @param filterTags Only return metrics that were submitted with tags matching this expression.
-     *     You can use AND, OR, IN, and wildcards (for example, service:web*). (optional)
+     *     You can use AND, OR, IN, and wildcards. For example: <code>
+     *     filter[tags]=env IN (staging,test) AND service:web*</code>. (optional)
      * @return ListTagConfigurationsOptionalParameters
      */
     public ListTagConfigurationsOptionalParameters filterTags(String filterTags) {
@@ -1723,8 +1727,10 @@ public ListTagConfigurationsOptionalParameters windowSeconds(Long windowSeconds)
     /**
      * Set pageSize.
      *
-     * @param pageSize Maximum number of results per page. Use with <code>page[cursor]</code> for
-     *     pagination. The default value is 10000, the maximum value is 10000, and the minimum value
+     * @param pageSize Maximum number of results per page. Send <code>page[size]</code> on the first
+     *     request to opt in to pagination. On each subsequent request, send <code>page[cursor]
+     *     </code> set to the value of <code>meta.pagination.next_cursor</code> from the previous
+     *     response. The default value is 10000, the maximum value is 10000, and the minimum value
      *     is 1. (optional, default to 10000)
      * @return ListTagConfigurationsOptionalParameters
      */
@@ -1867,6 +1873,11 @@ public PaginationIterable<MetricsAndMetricTagConfigurations> listTagConfiguratio
    * Get a list of actively reporting metrics for your organization. Pagination is optional using
    * the <code>page[cursor]</code> and <code>page[size]</code> query parameters.
    *
+   * <p>Query parameters use bracket notation (for example, <code>filter[tags]</code>, <code>
+   * filter[queried][window][seconds]</code>). Pass them as standard URL query strings, URL-encoding
+   * the brackets if your client does not handle them. For example: <code>
+   * GET /api/v2/metrics?filter[tags]=env:prod&amp;window[seconds]=86400&amp;page[size]=500</code>.
+   *
    * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;MetricsAndMetricTagConfigurationsResponse&gt;
    * @throws ApiException if fails to make API call