Clarify metrics API query strings (#3459)

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/datadog_api_client/v2/api/metrics_api.py

@@ -668,7 +668,7 @@ def estimate_metrics_output_series(
 
         :param metric_name: The name of the metric.
         :type metric_name: str
-        :param filter_groups: Filtered tag keys that the metric is configured to query with.
+        :param filter_groups: Comma-separated list of tag keys that the metric is configured to query with. For example: ``filter[groups]=app,host``.
         :type filter_groups: str, optional
         :param filter_hours_ago: The number of hours of look back (from now) to estimate cardinality with. If unspecified, it defaults to 0 hours.
         :type filter_hours_ago: int, optional
@@ -795,6 +795,8 @@ def list_tag_configurations(
 
         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 filter_configured: Only return custom metrics that have been configured with Metrics Without Limits.
         :type filter_configured: bool, optional
         :param filter_tags_configured: Only return metrics that have the given tag key(s) in their Metrics Without Limits configuration (included or excluded).
@@ -805,15 +807,15 @@ def list_tag_configurations(
         :type filter_include_percentiles: bool, optional
         :param 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.
         :type filter_queried: bool, optional
-        :param 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.
+        :param 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``.
         :type filter_queried_window_seconds: int, optional
-        :param 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*).
+        :param 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*``.
         :type filter_tags: str, optional
         :param filter_related_assets: Only return metrics that are used in at least one dashboard, monitor, notebook, or SLO.
         :type filter_related_assets: bool, optional
         :param 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.
         :type window_seconds: int, optional
-        :param 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.
+        :param 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.
         :type page_size: int, optional
         :param 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.
         :type page_cursor: str, optional
@@ -884,15 +886,15 @@ def list_tag_configurations_with_pagination(
         :type filter_include_percentiles: bool, optional
         :param 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.
         :type filter_queried: bool, optional
-        :param 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.
+        :param 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``.
         :type filter_queried_window_seconds: int, optional
-        :param 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*).
+        :param 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*``.
         :type filter_tags: str, optional
         :param filter_related_assets: Only return metrics that are used in at least one dashboard, monitor, notebook, or SLO.
         :type filter_related_assets: bool, optional
         :param 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.
         :type window_seconds: int, optional
-        :param 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.
+        :param 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.
         :type page_size: int, optional
         :param 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.
         :type page_cursor: str, optional