Clarify metrics API query strings (#4026)

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]

services/metrics/src/v2/MetricsApi.ts

@@ -2033,7 +2033,7 @@ export interface MetricsApiEstimateMetricsOutputSeriesRequest {
    */
   metricName: string;
   /**
-   * Filtered tag keys that the metric is configured to query with.
+   * Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`.
    * @type string
    */
   filterGroups?: string;
@@ -2124,12 +2124,12 @@ export interface MetricsApiListTagConfigurationsRequest {
    */
   filterQueried?: boolean;
   /**
-   * 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`.
    * @type number
    */
   filterQueriedWindowSeconds?: number;
   /**
-   * 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*`.
    * @type string
    */
   filterTags?: string;
@@ -2144,7 +2144,7 @@ export interface MetricsApiListTagConfigurationsRequest {
    */
   windowSeconds?: number;
   /**
-   * 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.
+   * 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.
    * @type number
    */
   pageSize?: number;
@@ -2491,6 +2491,8 @@ export class MetricsApi {
 
   /**
    * 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 param The request object
    */
   public listTagConfigurations(