Add edited_before and viewed_before filters to ListDashboardsUsage (#1690)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -27293,7 +27293,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"
@@ -27332,7 +27332,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
@@ -27341,11 +27341,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
@@ -117452,7 +117452,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.
@@ -117472,6 +117472,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:
@@ -117553,7 +117567,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.rs

@@ -0,0 +1,23 @@
+// Get usage stats for all dashboards with edited_before filter returns "OK"
+// response
+use datadog_api_client::datadog;
+use datadog_api_client::datadogV2::api_dashboards::DashboardsAPI;
+use datadog_api_client::datadogV2::api_dashboards::ListDashboardsUsageOptionalParams;
+
+#[tokio::main]
+async fn main() {
+    let mut configuration = datadog::Configuration::new();
+    configuration.set_unstable_operation_enabled("v2.ListDashboardsUsage", true);
+    let api = DashboardsAPI::with_config(configuration);
+    let resp = api
+        .list_dashboards_usage(
+            ListDashboardsUsageOptionalParams::default()
+                .filter_edited_before("2025-04-26T00:00:00Z".to_string()),
+        )
+        .await;
+    if let Ok(value) = resp {
+        println!("{:#?}", value);
+    } else {
+        println!("{:#?}", resp.unwrap_err());
+    }
+}

examples/v2_dashboards_ListDashboardsUsage_3946782296.rs

@@ -0,0 +1,23 @@
+// Get usage stats for all dashboards with viewed_before filter returns "OK"
+// response
+use datadog_api_client::datadog;
+use datadog_api_client::datadogV2::api_dashboards::DashboardsAPI;
+use datadog_api_client::datadogV2::api_dashboards::ListDashboardsUsageOptionalParams;
+
+#[tokio::main]
+async fn main() {
+    let mut configuration = datadog::Configuration::new();
+    configuration.set_unstable_operation_enabled("v2.ListDashboardsUsage", true);
+    let api = DashboardsAPI::with_config(configuration);
+    let resp = api
+        .list_dashboards_usage(
+            ListDashboardsUsageOptionalParams::default()
+                .filter_viewed_before("2025-04-26T00:00:00Z".to_string()),
+        )
+        .await;
+    if let Ok(value) = resp {
+        println!("{:#?}", value);
+    } else {
+        println!("{:#?}", resp.unwrap_err());
+    }
+}

examples/v2_dashboards_ListDashboardsUsage_4183300898.rs

@@ -0,0 +1,23 @@
+// Get usage stats for all dashboards with both filters returns "OK" response
+use datadog_api_client::datadog;
+use datadog_api_client::datadogV2::api_dashboards::DashboardsAPI;
+use datadog_api_client::datadogV2::api_dashboards::ListDashboardsUsageOptionalParams;
+
+#[tokio::main]
+async fn main() {
+    let mut configuration = datadog::Configuration::new();
+    configuration.set_unstable_operation_enabled("v2.ListDashboardsUsage", true);
+    let api = DashboardsAPI::with_config(configuration);
+    let resp = api
+        .list_dashboards_usage(
+            ListDashboardsUsageOptionalParams::default()
+                .filter_edited_before("2025-04-26T00:00:00Z".to_string())
+                .filter_viewed_before("2025-04-26T00:00:00Z".to_string()),
+        )
+        .await;
+    if let Ok(value) = resp {
+        println!("{:#?}", value);
+    } else {
+        println!("{:#?}", resp.unwrap_err());
+    }
+}

src/datadogV2/api/api_dashboards.rs

@@ -16,6 +16,10 @@ pub struct ListDashboardsUsageOptionalParams {
     pub page_limit: Option<i64>,
     /// Zero-based offset into the result set.
     pub page_offset: Option<i64>,
+    /// 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.
+    pub filter_edited_before: Option<String>,
+    /// 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.
+    pub filter_viewed_before: Option<String>,
 }
 
 impl ListDashboardsUsageOptionalParams {
@@ -29,6 +33,16 @@ impl ListDashboardsUsageOptionalParams {
         self.page_offset = Some(value);
         self
     }
+    /// 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.
+    pub fn filter_edited_before(mut self, value: String) -> Self {
+        self.filter_edited_before = Some(value);
+        self
+    }
+    /// 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.
+    pub fn filter_viewed_before(mut self, value: String) -> Self {
+        self.filter_viewed_before = Some(value);
+        self
+    }
 }
 
 /// GetDashboardUsageError is a struct for typed errors of method [`DashboardsAPI::get_dashboard_usage`]
@@ -124,7 +138,7 @@ impl DashboardsAPI {
         Self { config, client }
     }
 
-    /// 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.
+    /// 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.
     pub async fn get_dashboard_usage(
         &self,
         dashboard_id: String,
@@ -146,7 +160,7 @@ impl DashboardsAPI {
         }
     }
 
-    /// 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.
+    /// 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.
     pub async fn get_dashboard_usage_with_http_info(
         &self,
         dashboard_id: String,
@@ -241,7 +255,7 @@ impl DashboardsAPI {
         }
     }
 
-    /// Get paginated usage statistics for every dashboard in the caller's organization. Use `page[limit]` and `page[offset]` to walk the result set.
+    /// 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.
     pub async fn list_dashboards_usage(
         &self,
         params: ListDashboardsUsageOptionalParams,
@@ -299,7 +313,7 @@ impl DashboardsAPI {
         }
     }
 
-    /// Get paginated usage statistics for every dashboard in the caller's organization. Use `page[limit]` and `page[offset]` to walk the result set.
+    /// 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.
     pub async fn list_dashboards_usage_with_http_info(
         &self,
         params: ListDashboardsUsageOptionalParams,
@@ -321,6 +335,8 @@ impl DashboardsAPI {
         // unbox and build optional parameters
         let page_limit = params.page_limit;
         let page_offset = params.page_offset;
+        let filter_edited_before = params.filter_edited_before;
+        let filter_viewed_before = params.filter_viewed_before;
 
         let local_client = &self.client;
 
@@ -339,6 +355,14 @@ impl DashboardsAPI {
             local_req_builder =
                 local_req_builder.query(&[("page[offset]", &local_query_param.to_string())]);
         };
+        if let Some(ref local_query_param) = filter_edited_before {
+            local_req_builder = local_req_builder
+                .query(&[("filter[edited_before]", &local_query_param.to_string())]);
+        };
+        if let Some(ref local_query_param) = filter_viewed_before {
+            local_req_builder = local_req_builder
+                .query(&[("filter[viewed_before]", &local_query_param.to_string())]);
+        };
 
         // build headers
         let mut headers = HeaderMap::new();

src/datadogV2/model/model_dashboard_usage.rs

@@ -11,7 +11,7 @@ use std::fmt::{self, Formatter};
 #[skip_serializing_none]
 #[derive(Clone, Debug, PartialEq, Serialize)]
 pub struct DashboardUsage {
-    /// Usage statistics for a dashboard.
+    /// 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.
     #[serde(rename = "attributes")]
     pub attributes: crate::datadogV2::model::DashboardUsageAttributes,
     /// The dashboard ID.

src/datadogV2/model/model_dashboard_usage_attributes.rs

@@ -6,7 +6,7 @@ use serde::{Deserialize, Deserializer, Serialize};
 use serde_with::skip_serializing_none;
 use std::fmt::{self, Formatter};
 
-/// Usage statistics for a dashboard.
+/// 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.
 #[non_exhaustive]
 #[skip_serializing_none]
 #[derive(Clone, Debug, PartialEq, Serialize)]
@@ -44,17 +44,17 @@ pub struct DashboardUsageAttributes {
     /// The dashboard title.
     #[serde(rename = "title")]
     pub title: Option<String>,
-    /// 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); `0` in orgs without RUM.
     #[serde(rename = "total_views")]
     pub total_views: Option<i64>,
-    /// View counts keyed by view type. Possible keys are `in_app`, `embed`, `public`, `shared`, `api`, and `unknown`.
+    /// 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.
     #[serde(
         rename = "total_views_by_type",
         default,
         with = "::serde_with::rust::double_option"
     )]
     pub total_views_by_type: Option<Option<std::collections::BTreeMap<String, i64>>>,
-    /// 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; `null` in orgs without RUM.
     #[serde(
         rename = "viewed_at",
         default,

tests/scenarios/cassettes/v2/dashboards/Get-usage-stats-for-all-dashboards-with-both-filters-returns-OK-response.frozen

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

tests/scenarios/cassettes/v2/dashboards/Get-usage-stats-for-all-dashboards-with-both-filters-returns-OK-response.json

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