diff --git a/.generator/schemas/v1/openapi.yaml b/.generator/schemas/v1/openapi.yaml
index 2d398cc12e49..7bb1ef98cf2a 100644
--- a/.generator/schemas/v1/openapi.yaml
+++ b/.generator/schemas/v1/openapi.yaml
@@ -37782,7 +37782,10 @@ paths:
       x-codegen-request-body-name: body
   /api/v1/query:
     get:
-      description: Query timeseries points.
+      description: |-
+        Query timeseries points. Datadog recommends using the v2
+        `/api/v2/query/timeseries` endpoint over this endpoint for
+        querying timeseries data.
       operationId: QueryMetrics
       parameters:
         - description: Start of the queried time period, seconds since the Unix epoch.
diff --git a/.generator/schemas/v2/openapi.yaml b/.generator/schemas/v2/openapi.yaml
index d8f50ea93052..a8f738df556d 100644
--- a/.generator/schemas/v2/openapi.yaml
+++ b/.generator/schemas/v2/openapi.yaml
@@ -175956,7 +175956,9 @@ paths:
     post:
       description: |-
         Query timeseries data across various data sources and
-        process the data by applying formulas and functions.
+        process the data by applying formulas and functions. Datadog recommends
+        using this endpoint over the v1 `/api/v1/query` endpoint for querying
+        timeseries data.
       operationId: QueryTimeseriesData
       requestBody:
         content:
diff --git a/lib/datadog_api_client/v1/api/metrics_api.rb b/lib/datadog_api_client/v1/api/metrics_api.rb
index c9f24365a742..98d2db966cc8 100644
--- a/lib/datadog_api_client/v1/api/metrics_api.rb
+++ b/lib/datadog_api_client/v1/api/metrics_api.rb
@@ -239,7 +239,9 @@ def query_metrics(from, to, query, opts = {})
 
     # Query timeseries points.
     #
-    # Query timeseries points.
+    # Query timeseries points. Datadog recommends using the v2
+    # `/api/v2/query/timeseries` endpoint over this endpoint for
+    # querying timeseries data.
     #
     # @param from [Integer] Start of the queried time period, seconds since the Unix epoch.
     # @param to [Integer] End of the queried time period, seconds since the Unix epoch.
diff --git a/lib/datadog_api_client/v2/api/metrics_api.rb b/lib/datadog_api_client/v2/api/metrics_api.rb
index 1b9d68b9c277..f4310543e890 100644
--- a/lib/datadog_api_client/v2/api/metrics_api.rb
+++ b/lib/datadog_api_client/v2/api/metrics_api.rb
@@ -1845,7 +1845,9 @@ def query_timeseries_data(body, opts = {})
     # Query timeseries data across multiple products.
     #
     # Query timeseries data across various data sources and
-    # process the data by applying formulas and functions.
+    # process the data by applying formulas and functions. Datadog recommends
+    # using this endpoint over the v1 `/api/v1/query` endpoint for querying
+    # timeseries data.
     #
     # @param body [TimeseriesFormulaQueryRequest] 
     # @param opts [Hash] the optional parameters