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.
This endpoint requires the dashboards_read permission.
OAuth apps require the dashboards_read authorization scope to access this endpoint.
Response containing usage statistics for a single dashboard.
Expand All
Field
Type
Description
data [required]
object
A single dashboard usage record.
attributes [required]
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.
author
object
A user referenced from a dashboard usage record (author or viewer).
handle
string
Datadog handle (login) of the user.
id
string
The user ID.
is_disabled
boolean
Whether the user account is disabled.
name
string
Display name of the user.
created_at
date-time
When the dashboard was created.
dashboard_quality_score
double
The dashboard quality score ranges from 0 to 1, with higher scores indicating stronger signals of quality
and usefulness. The value is null when no score is available.
The score considers the following factors:
Dashboard and widget naming, including whether the dashboard uses a default or templated name
The number of data widgets, excluding container and text widgets
Confirmed broken queries
Recent activity, based on the last view date or, when no view date is available, the last edit or
creation date
Dashboards linked from monitors do not receive lower scores because of their naming or lack of recent
activity. An age-based adjustment helps prevent newly created dashboards from receiving disproportionately
low scores. Queries lower the score only when confirmed broken.
edited_at
date-time
When the dashboard was most recently edited.
org_id [required]
int64
The Datadog organization that owns the dashboard.
teams
[string]
Teams the dashboard is tagged with.
title
string
The dashboard title.
total_views
int64
Total view count for the dashboard. Counts only views captured by Real User Monitoring (RUM); 0 in orgs without RUM.
total_views_by_type
object
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.
<any-key>
int64
View count for that view type.
viewed_at
date-time
When the dashboard was most recently viewed. Populated only when Real User Monitoring (RUM) is active for the org; null in orgs without RUM.
viewer
object
A user referenced from a dashboard usage record (author or viewer).
handle
string
Datadog handle (login) of the user.
id
string
The user ID.
is_disabled
boolean
Whether the user account is disabled.
name
string
Display name of the user.
widget_count
int64
The total number of widgets on the dashboard.
widget_count_by_type
object
Widget counts keyed by widget type. The map includes group widgets and widgets without requests.
<any-key>
int64
Widget count for that widget type.
id [required]
string
The dashboard ID.
type [required]
enum
The type of the resource. Always dashboards-usages.
Allowed enum values: dashboards-usages
default: dashboards-usages
{"data":{"attributes":{"author":{"handle":"jane.doe@example.com","id":"00000000-0000-0000-0000-000000000000","is_disabled":false,"name":"Jane Doe"},"created_at":"2026-01-15T09:30:00.000Z","dashboard_quality_score":0.85,"edited_at":"2026-04-20T11:05:00.000Z","org_id":100,"teams":[],"title":"My production overview","total_views":42,"total_views_by_type":{"<any-key>":"integer"},"viewed_at":"2026-05-01T14:22:10.000Z","viewer":{"handle":"jane.doe@example.com","id":"00000000-0000-0000-0000-000000000000","is_disabled":false,"name":"Jane Doe"},"widget_count":12,"widget_count_by_type":{"<any-key>":"integer"}},"id":"q5j-nti-fv6","type":"dashboards-usages"}}
# Path parameters exportdashboard_id="q5j-nti-fv6" # Use a Personal Access Token or Service Access Token exportDD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
"""
Get usage stats for a dashboard returns "OK" response
"""fromosimportenvironfromdatadog_api_clientimportApiClient,Configurationfromdatadog_api_client.v2.api.dashboards_apiimportDashboardsApi# there is a valid "dashboard" in the systemDASHBOARD_ID=environ["DASHBOARD_ID"]configuration=Configuration()configuration.access_token=environ["DD_BEARER_TOKEN"]configuration.unstable_operations["get_dashboard_usage"]=TruewithApiClient(configuration)asapi_client:api_instance=DashboardsApi(api_client)response=api_instance.get_dashboard_usage(dashboard_id=DASHBOARD_ID,)print(response)
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"python3"example.py"
# Get usage stats for a dashboard returns "OK" responserequire"datadog_api_client"DatadogAPIClient.configuredo|config|config.access_token=ENV["DD_BEARER_TOKEN"]config.unstable_operations["v2.get_dashboard_usage".to_sym]=trueendapi_instance=DatadogAPIClient::V2::DashboardsAPI.new# there is a valid "dashboard" in the systemDASHBOARD_ID=ENV["DASHBOARD_ID"]papi_instance.get_dashboard_usage(DASHBOARD_ID)
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"rb"example.rb"
// Get usage stats for a dashboard returns "OK" responsepackagemainimport("context""encoding/json""fmt""os""github.com/DataDog/datadog-api-client-go/v2/api/datadog""github.com/DataDog/datadog-api-client-go/v2/api/datadogV2")funcmain(){// there is a valid "dashboard" in the systemDashboardID:=os.Getenv("DASHBOARD_ID")ctx:=datadog.NewDefaultContext(context.Background())ctx=context.WithValue(ctx,datadog.ContextAccessToken,os.Getenv("DD_BEARER_TOKEN"))configuration:=datadog.NewConfiguration()configuration.SetUnstableOperationEnabled("v2.GetDashboardUsage",true)apiClient:=datadog.NewAPIClient(configuration)api:=datadogV2.NewDashboardsApi(apiClient)resp,r,err:=api.GetDashboardUsage(ctx,DashboardID)iferr!=nil{fmt.Fprintf(os.Stderr,"Error when calling `DashboardsApi.GetDashboardUsage`: %v\n",err)fmt.Fprintf(os.Stderr,"Full HTTP response: %v\n",r)}responseContent,_:=json.MarshalIndent(resp,""," ")fmt.Fprintf(os.Stdout,"Response from `DashboardsApi.GetDashboardUsage`:\n%s\n",responseContent)}
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"go run"main.go"
// Get usage stats for a dashboard returns "OK" responseimportcom.datadog.api.client.ApiClient;importcom.datadog.api.client.ApiException;importcom.datadog.api.client.v2.api.DashboardsApi;importcom.datadog.api.client.v2.model.DashboardUsageResponse;publicclassExample{publicstaticvoidmain(String[]args){ApiClientdefaultClient=ApiClient.getDefaultApiClient();defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));defaultClient.setUnstableOperationEnabled("v2.getDashboardUsage",true);DashboardsApiapiInstance=newDashboardsApi(defaultClient);// there is a valid "dashboard" in the systemStringDASHBOARD_ID=System.getenv("DASHBOARD_ID");try{DashboardUsageResponseresult=apiInstance.getDashboardUsage(DASHBOARD_ID);System.out.println(result);}catch(ApiExceptione){System.err.println("Exception when calling DashboardsApi#getDashboardUsage");System.err.println("Status code: "+e.getCode());System.err.println("Reason: "+e.getResponseBody());System.err.println("Response headers: "+e.getResponseHeaders());e.printStackTrace();}}}
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"java"Example.java"
// Get usage stats for a dashboard returns "OK" response
usedatadog_api_client::datadog;usedatadog_api_client::datadogV2::api_dashboards::DashboardsAPI;#[tokio::main]asyncfnmain(){// there is a valid "dashboard" in the system
letdashboard_id=std::env::var("DASHBOARD_ID").unwrap();letmutconfiguration=datadog::Configuration::new();configuration.set_unstable_operation_enabled("v2.get_dashboard_usage",true);letapi=DashboardsAPI::with_config(configuration);letresp=api.get_dashboard_usage(dashboard_id.clone()).await;ifletOk(value)=resp{println!("{:#?}",value);}else{println!("{:#?}",resp.unwrap_err());}}
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_API_KEY="<DD_API_KEY>"DD_APP_KEY="<DD_APP_KEY>"cargo run
/**
* Get usage stats for a dashboard returns "OK" response
*/import{client,v2}from"@datadog/datadog-api-client";constconfiguration=client.createConfiguration({authMethods:{AuthZ:{accessToken: process.env.DD_BEARER_TOKENasstring,},},});configuration.unstableOperations["v2.getDashboardUsage"]=true;constapiInstance=newv2.DashboardsApi(configuration);// there is a valid "dashboard" in the system
constDASHBOARD_ID=process.env.DASHBOARD_IDasstring;constparams: v2.DashboardsApiGetDashboardUsageRequest={dashboardId: DASHBOARD_ID,};apiInstance.getDashboardUsage(params).then((data: v2.DashboardUsageResponse)=>{console.log("API called successfully. Returned data: "+JSON.stringify(data));}).catch((error: any)=>console.error(error));
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"tsc"example.ts"
Request a personalized demo
Get Started with Datadog
Ask AI
AI-generated responses may be inaccurate. Verify important info.