dashboard_usage

Creates, updates, deletes, gets or lists a dashboard_usage resource.

Overview

Name	dashboard_usage
Type	Resource
Id	datadog.dashboards.dashboard_usage

Fields

The following fields are returned by SELECT queries:

get_dashboard_usage

Name	Datatype	Description
id	string	The dashboard ID. (example: q5j-nti-fv6)
attributes	object	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	string	The type of the resource. Always dashboards-usages. (dashboards-usages) (default: dashboards-usages, example: dashboards-usages)

list_dashboards_usage

Name	Datatype	Description
id	string	The dashboard ID. (example: q5j-nti-fv6)
attributes	object	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	string	The type of the resource. Always dashboards-usages. (dashboards-usages) (default: dashboards-usages, example: dashboards-usages)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_dashboard_usage	select	dashboard_id		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. View counts are refreshed once per day and only reflect views recorded starting January 2025; views prior to that date are not included.
list_dashboards_usage	select		page[limit], page[offset], filter[edited_before], filter[viewed_before]	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 edit or view date. View-count fields depend on Real User Monitoring (RUM) and are null or 0 in orgs without RUM. View counts are refreshed once per day and only reflect views recorded starting January 2025; views prior to that date are not included.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
dashboard_id	string	The ID of the dashboard.
site	string	The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both.
filter[edited_before]	string	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.
filter[viewed_before]	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.
page[limit]	integer (int64)	Maximum number of dashboards to return per page. Server-side maximum is 500; values above 500 return a 400 Bad Request.
page[offset]	integer (int64)	Zero-based offset into the result set.

SELECT examples

get_dashboard_usage

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. View counts are refreshed once per day and only reflect views recorded starting January 2025; views prior to that date are not included.

SELECT
id,
attributes,
type
FROM datadog.dashboards.dashboard_usage
WHERE dashboard_id = '{{ dashboard_id }}' -- required
;

list_dashboards_usage

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 edit or view date. View-count fields depend on Real User Monitoring (RUM) and are null or 0 in orgs without RUM. View counts are refreshed once per day and only reflect views recorded starting January 2025; views prior to that date are not included.

SELECT
id,
attributes,
type
FROM datadog.dashboards.dashboard_usage
WHERE page[limit] = '{{ page[limit] }}'
AND page[offset] = '{{ page[offset] }}'
AND filter[edited_before] = '{{ filter[edited_before] }}'
AND filter[viewed_before] = '{{ filter[viewed_before] }}'
;