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.py

@@ -0,0 +1,16 @@
+"""
+Get usage stats for all dashboards with edited_before filter returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.dashboards_api import DashboardsApi
+
+configuration = Configuration()
+configuration.unstable_operations["list_dashboards_usage"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.list_dashboards_usage(
+        filter_edited_before="2025-04-26T00:00:00Z",
+    )
+
+    print(response)

examples/v2/dashboards/ListDashboardsUsage_3946782296.py

@@ -0,0 +1,16 @@
+"""
+Get usage stats for all dashboards with viewed_before filter returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.dashboards_api import DashboardsApi
+
+configuration = Configuration()
+configuration.unstable_operations["list_dashboards_usage"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.list_dashboards_usage(
+        filter_viewed_before="2025-04-26T00:00:00Z",
+    )
+
+    print(response)

examples/v2/dashboards/ListDashboardsUsage_4183300898.py

@@ -0,0 +1,17 @@
+"""
+Get usage stats for all dashboards with both filters returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.dashboards_api import DashboardsApi
+
+configuration = Configuration()
+configuration.unstable_operations["list_dashboards_usage"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = DashboardsApi(api_client)
+    response = api_instance.list_dashboards_usage(
+        filter_edited_before="2025-04-26T00:00:00Z",
+        filter_viewed_before="2025-04-26T00:00:00Z",
+    )
+
+    print(response)

src/datadog_api_client/v2/api/dashboards_api.py

@@ -78,6 +78,16 @@ def __init__(self, api_client=None):
                     "attribute": "page[offset]",
                     "location": "query",
                 },
+                "filter_edited_before": {
+                    "openapi_types": (str,),
+                    "attribute": "filter[edited_before]",
+                    "location": "query",
+                },
+                "filter_viewed_before": {
+                    "openapi_types": (str,),
+                    "attribute": "filter[viewed_before]",
+                    "location": "query",
+                },
             },
             headers_map={
                 "accept": ["application/json"],
@@ -91,7 +101,7 @@ def get_dashboard_usage(
     ) -> DashboardUsageResponse:
         """Get usage stats for a dashboard.
 
-        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.
 
         :param dashboard_id: The ID of the dashboard.
         :type dashboard_id: str
@@ -107,15 +117,21 @@ def list_dashboards_usage(
         *,
         page_limit: Union[int, UnsetType] = unset,
         page_offset: Union[int, UnsetType] = unset,
+        filter_edited_before: Union[str, UnsetType] = unset,
+        filter_viewed_before: Union[str, UnsetType] = unset,
     ) -> ListDashboardsUsageResponse:
         """Get usage stats for all dashboards.
 
-        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.
 
         :param page_limit: Maximum number of dashboards to return per page. Server-side maximum is 500; values above 500 return a 400 Bad Request.
         :type page_limit: int, optional
         :param page_offset: Zero-based offset into the result set.
         :type page_offset: int, optional
+        :param filter_edited_before: 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.
+        :type filter_edited_before: str, optional
+        :param filter_viewed_before: 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.
+        :type filter_viewed_before: str, optional
         :rtype: ListDashboardsUsageResponse
         """
         kwargs: Dict[str, Any] = {}
@@ -125,13 +141,21 @@ def list_dashboards_usage(
         if page_offset is not unset:
             kwargs["page_offset"] = page_offset
 
+        if filter_edited_before is not unset:
+            kwargs["filter_edited_before"] = filter_edited_before
+
+        if filter_viewed_before is not unset:
+            kwargs["filter_viewed_before"] = filter_viewed_before
+
         return self._list_dashboards_usage_endpoint.call_with_http_info(**kwargs)
 
     def list_dashboards_usage_with_pagination(
         self,
         *,
         page_limit: Union[int, UnsetType] = unset,
         page_offset: Union[int, UnsetType] = unset,
+        filter_edited_before: Union[str, UnsetType] = unset,
+        filter_viewed_before: Union[str, UnsetType] = unset,
     ) -> collections.abc.Iterable[DashboardUsage]:
         """Get usage stats for all dashboards.
 
@@ -141,6 +165,10 @@ def list_dashboards_usage_with_pagination(
         :type page_limit: int, optional
         :param page_offset: Zero-based offset into the result set.
         :type page_offset: int, optional
+        :param filter_edited_before: 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.
+        :type filter_edited_before: str, optional
+        :param filter_viewed_before: 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.
+        :type filter_viewed_before: str, optional
 
         :return: A generator of paginated results.
         :rtype: collections.abc.Iterable[DashboardUsage]
@@ -152,6 +180,12 @@ def list_dashboards_usage_with_pagination(
         if page_offset is not unset:
             kwargs["page_offset"] = page_offset
 
+        if filter_edited_before is not unset:
+            kwargs["filter_edited_before"] = filter_edited_before
+
+        if filter_viewed_before is not unset:
+            kwargs["filter_viewed_before"] = filter_viewed_before
+
         local_page_size = get_attribute_from_path(kwargs, "page_limit", 250)
         endpoint = self._list_dashboards_usage_endpoint
         set_attribute_from_path(kwargs, "page_limit", local_page_size, endpoint.params_map)

src/datadog_api_client/v2/model/dashboard_usage.py

@@ -38,7 +38,7 @@ def __init__(self_, attributes: DashboardUsageAttributes, id: str, type: Dashboa
         """
         A single dashboard usage record.
 
-        :param attributes: Usage statistics for a dashboard.
+        :param attributes: 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.
         :type attributes: DashboardUsageAttributes
 
         :param id: The dashboard ID.

src/datadog_api_client/v2/model/dashboard_usage_attributes.py

@@ -74,7 +74,7 @@ def __init__(
         **kwargs,
     ):
         """
-        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.
 
         :param author: A user referenced from a dashboard usage record (author or viewer).
         :type author: DashboardUsageUser, none_type, optional
@@ -97,13 +97,13 @@ def __init__(
         :param title: The dashboard title.
         :type title: str, optional
 
-        :param total_views: The total number of times the dashboard has been viewed.
+        :param total_views: Total view count for the dashboard. Counts only views captured by Real User Monitoring (RUM); ``0`` in orgs without RUM.
         :type total_views: int, optional
 
-        :param total_views_by_type: View counts keyed by view type. Possible keys are ``in_app`` , ``embed`` , ``public`` , ``shared`` , ``api`` , and ``unknown``.
+        :param total_views_by_type: 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.
         :type total_views_by_type: {str: (int,)}, none_type, optional
 
-        :param viewed_at: When the dashboard was most recently viewed.
+        :param viewed_at: When the dashboard was most recently viewed. Populated only when Real User Monitoring (RUM) is active for the org; ``null`` in orgs without RUM.
         :type viewed_at: datetime, none_type, optional
 
         :param viewer: A user referenced from a dashboard usage record (author or viewer).

tests/v2/cassettes/test_scenarios/test_get_usage_stats_for_all_dashboards_with_both_filters_returns_ok_response.frozen

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