Add edited_before and viewed_before filters to ListDashboardsUsage

.generator/schemas/v2/openapi.yaml

@@ -26248,7 +26248,7 @@ components:
         - attributes
       type: object
     DashboardUsageAttributes:
-      description: Usage statistics for a dashboard.
+      description: Usage statistics for a dashboard. The `viewer` field and all view-count fields (`total_views`, `viewed_at`, `total_views_by_type`) are populated only when Real User Monitoring (RUM) is active for the org.
       properties:
         author:
           $ref: "#/components/schemas/DashboardUsageUser"
@@ -26287,7 +26287,7 @@ components:
           example: My production overview
           type: string
         total_views:
-          description: The total number of times the dashboard has been viewed.
+          description: Total view count for the dashboard. Counts only views captured by Real User Monitoring (RUM); `0` in orgs without RUM.
           example: 42
           format: int64
           type: integer
@@ -26296,11 +26296,11 @@ components:
             description: View count for that view type.
             format: int64
             type: integer
-          description: View counts keyed by view type. Possible keys are `in_app`, `embed`, `public`, `shared`, `api`, and `unknown`.
+          description: View counts keyed by view type (`in_app`, `embed`, `public`, `shared`, `api`, `unknown`). Counts only views captured by Real User Monitoring (RUM); empty in orgs without RUM.
           nullable: true
           type: object
         viewed_at:
-          description: When the dashboard was most recently viewed.
+          description: When the dashboard was most recently viewed. Populated only when Real User Monitoring (RUM) is active for the org; `null` in orgs without RUM.
           example: "2026-05-01T14:22:10.000Z"
           format: date-time
           nullable: true
@@ -115352,7 +115352,7 @@ paths:
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/dashboards/usage:
     get:
-      description: Get paginated usage statistics for every dashboard in the caller's organization. Use `page[limit]` and `page[offset]` to walk the result set.
+      description: Get paginated usage statistics for every dashboard in the caller's organization. Use `page[limit]` and `page[offset]` to walk the result set. Use `filter[edited_before]` or `filter[viewed_before]` to narrow results by recency. View-count fields depend on Real User Monitoring (RUM) and are `null` or `0` in orgs without RUM.
       operationId: ListDashboardsUsage
       parameters:
         - description: Maximum number of dashboards to return per page. Server-side maximum is 500; values above 500 return a 400 Bad Request.
@@ -115372,6 +115372,20 @@ paths:
             format: int64
             minimum: 0
             type: integer
+        - description: Return only dashboards whose last edit (`edited_at`) is strictly before this ISO 8601 timestamp (`edited_at < value`; boundary matches are excluded). Must include a timezone offset (for example, `Z` or `+00:00`); naive timestamps return HTTP 400.
+          in: query
+          name: filter[edited_before]
+          required: false
+          schema:
+            example: "2025-04-26T00:00:00Z"
+            type: string
+        - description: Return only dashboards whose most recent view (`viewed_at`) is strictly before this ISO 8601 timestamp, including dashboards that have never been viewed. Must include a timezone offset; naive timestamps return HTTP 400. Orgs without Real User Monitoring (RUM) will see all dashboards returned by this filter.
+          in: query
+          name: filter[viewed_before]
+          required: false
+          schema:
+            example: "2025-04-26T00:00:00Z"
+            type: string
       responses:
         "200":
           content:
@@ -115453,7 +115467,7 @@ paths:
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/dashboards/{dashboard_id}/usage:
     get:
-      description: Get usage statistics for a single dashboard. The response includes view counts, the most recent view and edit times, widget counts, and the dashboard quality score.
+      description: Get usage statistics for a single dashboard. The response includes view counts, the most recent view and edit times, widget counts, and the dashboard quality score. View-count fields depend on Real User Monitoring (RUM) and are `null` or `0` in orgs without RUM.
       operationId: GetDashboardUsage
       parameters:
         - description: The ID of the dashboard.

examples/v2/dashboards/ListDashboardsUsage_3889372739.java

@@ -0,0 +1,29 @@
+// Get usage stats for all dashboards with edited_before filter returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.DashboardsApi;
+import com.datadog.api.client.v2.api.DashboardsApi.ListDashboardsUsageOptionalParameters;
+import com.datadog.api.client.v2.model.ListDashboardsUsageResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.listDashboardsUsage", true);
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    try {
+      ListDashboardsUsageResponse result =
+          apiInstance.listDashboardsUsage(
+              new ListDashboardsUsageOptionalParameters()
+                  .filterEditedBefore("2025-04-26T00:00:00Z"));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#listDashboardsUsage");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v2/dashboards/ListDashboardsUsage_3946782296.java

@@ -0,0 +1,29 @@
+// Get usage stats for all dashboards with viewed_before filter returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.DashboardsApi;
+import com.datadog.api.client.v2.api.DashboardsApi.ListDashboardsUsageOptionalParameters;
+import com.datadog.api.client.v2.model.ListDashboardsUsageResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.listDashboardsUsage", true);
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    try {
+      ListDashboardsUsageResponse result =
+          apiInstance.listDashboardsUsage(
+              new ListDashboardsUsageOptionalParameters()
+                  .filterViewedBefore("2025-04-26T00:00:00Z"));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#listDashboardsUsage");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v2/dashboards/ListDashboardsUsage_4183300898.java

@@ -0,0 +1,30 @@
+// Get usage stats for all dashboards with both filters returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.DashboardsApi;
+import com.datadog.api.client.v2.api.DashboardsApi.ListDashboardsUsageOptionalParameters;
+import com.datadog.api.client.v2.model.ListDashboardsUsageResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.listDashboardsUsage", true);
+    DashboardsApi apiInstance = new DashboardsApi(defaultClient);
+
+    try {
+      ListDashboardsUsageResponse result =
+          apiInstance.listDashboardsUsage(
+              new ListDashboardsUsageOptionalParameters()
+                  .filterEditedBefore("2025-04-26T00:00:00Z")
+                  .filterViewedBefore("2025-04-26T00:00:00Z"));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling DashboardsApi#listDashboardsUsage");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

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

@@ -79,7 +79,8 @@ public CompletableFuture<DashboardUsageResponse> getDashboardUsageAsync(String d
 
   /**
    * Get usage statistics for a single dashboard. The response includes view counts, the most recent
-   * view and edit times, widget counts, and the dashboard quality score.
+   * view and edit times, widget counts, and the dashboard quality score. View-count fields depend
+   * on Real User Monitoring (RUM) and are <code>null</code> or <code>0</code> in orgs without RUM.
    *
    * @param dashboardId The ID of the dashboard. (required)
    * @return ApiResponse&lt;DashboardUsageResponse&gt;
@@ -208,6 +209,8 @@ public CompletableFuture<ApiResponse<DashboardUsageResponse>> getDashboardUsageW
   public static class ListDashboardsUsageOptionalParameters {
     private Long pageLimit;
     private Long pageOffset;
+    private String filterEditedBefore;
+    private String filterViewedBefore;
 
     /**
      * Set pageLimit.
@@ -231,6 +234,35 @@ public ListDashboardsUsageOptionalParameters pageOffset(Long pageOffset) {
       this.pageOffset = pageOffset;
       return this;
     }
+
+    /**
+     * Set filterEditedBefore.
+     *
+     * @param filterEditedBefore Return only dashboards whose last edit (<code>edited_at</code>) is
+     *     strictly before this ISO 8601 timestamp (<code>edited_at &lt; value</code>; boundary
+     *     matches are excluded). Must include a timezone offset (for example, <code>Z</code> or
+     *     <code>+00:00</code>); naive timestamps return HTTP 400. (optional)
+     * @return ListDashboardsUsageOptionalParameters
+     */
+    public ListDashboardsUsageOptionalParameters filterEditedBefore(String filterEditedBefore) {
+      this.filterEditedBefore = filterEditedBefore;
+      return this;
+    }
+
+    /**
+     * Set filterViewedBefore.
+     *
+     * @param filterViewedBefore Return only dashboards whose most recent view (<code>viewed_at
+     *     </code>) is strictly before this ISO 8601 timestamp, including dashboards that have never
+     *     been viewed. Must include a timezone offset; naive timestamps return HTTP 400. Orgs
+     *     without Real User Monitoring (RUM) will see all dashboards returned by this filter.
+     *     (optional)
+     * @return ListDashboardsUsageOptionalParameters
+     */
+    public ListDashboardsUsageOptionalParameters filterViewedBefore(String filterViewedBefore) {
+      this.filterViewedBefore = filterViewedBefore;
+      return this;
+    }
   }
 
   /**
@@ -347,7 +379,10 @@ public PaginationIterable<DashboardUsage> listDashboardsUsageWithPagination(
 
   /**
    * Get paginated usage statistics for every dashboard in the caller's organization. Use <code>
-   * page[limit]</code> and <code>page[offset]</code> to walk the result set.
+   * page[limit]</code> and <code>page[offset]</code> to walk the result set. Use <code>
+   * filter[edited_before]</code> or <code>filter[viewed_before]</code> to narrow results by
+   * recency. View-count fields depend on Real User Monitoring (RUM) and are <code>null</code> or
+   * <code>0</code> in orgs without RUM.
    *
    * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;ListDashboardsUsageResponse&gt;
@@ -374,6 +409,8 @@ public ApiResponse<ListDashboardsUsageResponse> listDashboardsUsageWithHttpInfo(
     Object localVarPostBody = null;
     Long pageLimit = parameters.pageLimit;
     Long pageOffset = parameters.pageOffset;
+    String filterEditedBefore = parameters.filterEditedBefore;
+    String filterViewedBefore = parameters.filterViewedBefore;
     // create path and map variables
     String localVarPath = "/api/v2/dashboards/usage";
 
@@ -382,6 +419,10 @@ public ApiResponse<ListDashboardsUsageResponse> listDashboardsUsageWithHttpInfo(
 
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[limit]", pageLimit));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[offset]", pageOffset));
+    localVarQueryParams.addAll(
+        apiClient.parameterToPairs("", "filter[edited_before]", filterEditedBefore));
+    localVarQueryParams.addAll(
+        apiClient.parameterToPairs("", "filter[viewed_before]", filterViewedBefore));
 
     Invocation.Builder builder =
         apiClient.createBuilder(
@@ -427,6 +468,8 @@ public ApiResponse<ListDashboardsUsageResponse> listDashboardsUsageWithHttpInfo(
     Object localVarPostBody = null;
     Long pageLimit = parameters.pageLimit;
     Long pageOffset = parameters.pageOffset;
+    String filterEditedBefore = parameters.filterEditedBefore;
+    String filterViewedBefore = parameters.filterViewedBefore;
     // create path and map variables
     String localVarPath = "/api/v2/dashboards/usage";
 
@@ -435,6 +478,10 @@ public ApiResponse<ListDashboardsUsageResponse> listDashboardsUsageWithHttpInfo(
 
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[limit]", pageLimit));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[offset]", pageOffset));
+    localVarQueryParams.addAll(
+        apiClient.parameterToPairs("", "filter[edited_before]", filterEditedBefore));
+    localVarQueryParams.addAll(
+        apiClient.parameterToPairs("", "filter[viewed_before]", filterViewedBefore));
 
     Invocation.Builder builder;
     try {

src/main/java/com/datadog/api/client/v2/model/DashboardUsage.java

@@ -58,7 +58,9 @@ public DashboardUsage attributes(DashboardUsageAttributes attributes) {
   }
 
   /**
-   * Usage statistics for a dashboard.
+   * Usage statistics for a dashboard. The <code>viewer</code> field and all view-count fields (
+   * <code>total_views</code>, <code>viewed_at</code>, <code>total_views_by_type</code>) are
+   * populated only when Real User Monitoring (RUM) is active for the org.
    *
    * @return attributes
    */

src/main/java/com/datadog/api/client/v2/model/DashboardUsageAttributes.java

@@ -21,7 +21,11 @@
 import java.util.Objects;
 import org.openapitools.jackson.nullable.JsonNullable;
 
-/** Usage statistics for a dashboard. */
+/**
+ * Usage statistics for a dashboard. The <code>viewer</code> field and all view-count fields (<code>
+ * total_views</code>, <code>viewed_at</code>, <code>total_views_by_type</code>) are populated only
+ * when Real User Monitoring (RUM) is active for the org.
+ */
 @JsonPropertyOrder({
   DashboardUsageAttributes.JSON_PROPERTY_AUTHOR,
   DashboardUsageAttributes.JSON_PROPERTY_CREATED_AT,
@@ -304,7 +308,8 @@ public DashboardUsageAttributes totalViews(Long totalViews) {
   }
 
   /**
-   * The total number of times the dashboard has been viewed.
+   * Total view count for the dashboard. Counts only views captured by Real User Monitoring (RUM);
+   * <code>0</code> in orgs without RUM.
    *
    * @return totalViews
    */
@@ -337,8 +342,9 @@ public DashboardUsageAttributes putTotalViewsByTypeItem(String key, Long totalVi
   }
 
   /**
-   * View counts keyed by view type. Possible keys are <code>in_app</code>, <code>embed</code>,
-   * <code>public</code>, <code>shared</code>, <code>api</code>, and <code>unknown</code>.
+   * View counts keyed by view type (<code>in_app</code>, <code>embed</code>, <code>public</code>,
+   * <code>shared</code>, <code>api</code>, <code>unknown</code>). Counts only views captured by
+   * Real User Monitoring (RUM); empty in orgs without RUM.
    *
    * @return totalViewsByType
    */
@@ -369,7 +375,8 @@ public DashboardUsageAttributes viewedAt(OffsetDateTime viewedAt) {
   }
 
   /**
-   * When the dashboard was most recently viewed.
+   * When the dashboard was most recently viewed. Populated only when Real User Monitoring (RUM) is
+   * active for the org; <code>null</code> in orgs without RUM.
    *
    * @return viewedAt
    */

src/test/resources/cassettes/features/v2/Get_usage_stats_for_all_dashboards_with_both_filters_returns_OK_response.freeze

@@ -0,0 +1 @@
+2026-06-01T18:15:39.812Z

src/test/resources/cassettes/features/v2/Get_usage_stats_for_all_dashboards_with_edited_before_filter_returns_OK_response.freeze

@@ -0,0 +1 @@
+2026-06-01T18:14:52.307Z

src/test/resources/cassettes/features/v2/Get_usage_stats_for_all_dashboards_with_viewed_before_filter_returns_OK_response.freeze

@@ -0,0 +1 @@
+2026-06-01T18:15:30.412Z

src/test/resources/com/datadog/api/client/v2/api/dashboards.feature

@@ -71,3 +71,31 @@ Feature: Dashboards
     When the request with pagination is sent
     Then the response status is 200 OK
     And the response has 590 items
+
+  @replay-only @team:DataDog/dashboards-backend
+  Scenario: Get usage stats for all dashboards with both filters returns "OK" response
+    Given operation "ListDashboardsUsage" enabled
+    And new "ListDashboardsUsage" request
+    And request contains "filter[edited_before]" parameter with value "2025-04-26T00:00:00Z"
+    And request contains "filter[viewed_before]" parameter with value "2025-04-26T00:00:00Z"
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "meta.page" has field "total"
+
+  @replay-only @team:DataDog/dashboards-backend
+  Scenario: Get usage stats for all dashboards with edited_before filter returns "OK" response
+    Given operation "ListDashboardsUsage" enabled
+    And new "ListDashboardsUsage" request
+    And request contains "filter[edited_before]" parameter with value "2025-04-26T00:00:00Z"
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "meta.page" has field "total"
+
+  @replay-only @team:DataDog/dashboards-backend
+  Scenario: Get usage stats for all dashboards with viewed_before filter returns "OK" response
+    Given operation "ListDashboardsUsage" enabled
+    And new "ListDashboardsUsage" request
+    And request contains "filter[viewed_before]" parameter with value "2025-04-26T00:00:00Z"
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "meta.page" has field "total"