diff --git a/.generator/schemas/v1/openapi.yaml b/.generator/schemas/v1/openapi.yaml
index 3d7f50c714c..7056d83d64b 100644
--- a/.generator/schemas/v1/openapi.yaml
+++ b/.generator/schemas/v1/openapi.yaml
@@ -37576,7 +37576,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 9e31333a3d0..0129d69d5e8 100644
--- a/.generator/schemas/v2/openapi.yaml
+++ b/.generator/schemas/v2/openapi.yaml
@@ -182209,7 +182209,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/src/main/java/com/datadog/api/client/v1/api/MetricsApi.java b/src/main/java/com/datadog/api/client/v1/api/MetricsApi.java
index b4213e5dbe3..3f19e749b31 100644
--- a/src/main/java/com/datadog/api/client/v1/api/MetricsApi.java
+++ b/src/main/java/com/datadog/api/client/v1/api/MetricsApi.java
@@ -583,7 +583,8 @@ public CompletableFuture<MetricsQueryResponse> queryMetricsAsync(
   }
 
   /**
-   * Query timeseries points.
+   * Query timeseries points. Datadog recommends using the v2 <code>/api/v2/query/timeseries</code>
+   * endpoint over this endpoint for querying timeseries data.
    *
    * @param from Start of the queried time period, seconds since the Unix epoch. (required)
    * @param to End of the queried time period, seconds since the Unix epoch. (required)
diff --git a/src/main/java/com/datadog/api/client/v2/api/MetricsApi.java b/src/main/java/com/datadog/api/client/v2/api/MetricsApi.java
index 2ff0bceffa1..e5772d51c3b 100644
--- a/src/main/java/com/datadog/api/client/v2/api/MetricsApi.java
+++ b/src/main/java/com/datadog/api/client/v2/api/MetricsApi.java
@@ -4622,7 +4622,8 @@ public CompletableFuture<TimeseriesFormulaQueryResponse> queryTimeseriesDataAsyn
 
   /**
    * Query timeseries data across various data sources and process the data by applying formulas and
-   * functions.
+   * functions. Datadog recommends using this endpoint over the v1 <code>/api/v1/query</code>
+   * endpoint for querying timeseries data.
    *
    * @param body (required)
    * @return ApiResponse&lt;TimeseriesFormulaQueryResponse&gt;