--- title: Get usage stats for a dashboard description: Get usage statistics for a single dashboard. breadcrumbs: Docs > API > Get usage stats for a dashboard --- > For the complete documentation index, see [llms.txt](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/llms.txt). # Get usage stats for a dashboard ## v2 (latest) {% alert level="warning" %} **Note**: This endpoint is in preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md). {% /alert %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------------ | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/dashboards/{dashboard_id}/usage | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/dashboards/{dashboard_id}/usage | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/dashboards/{dashboard_id}/usage | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/dashboards/{dashboard_id}/usage | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/dashboards/{dashboard_id}/usage | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/dashboards/{dashboard_id}/usage | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/dashboards/{dashboard_id}/usage | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/dashboards/{dashboard_id}/usage | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/dashboards/{dashboard_id}/usage | ### Overview 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](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/scopes.md#dashboards) to access this endpoint. ### Arguments #### Path Parameters | Field | Type | Description | | ------------------------- | ------ | ------------------------ | | dashboard_id [*required*] | string | The ID of the dashboard. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing usage statistics for a single dashboard. | Parent field | Field | Type | Description | | -------------------- | ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | A single dashboard usage record. | | data | 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. | | attributes | author | object | A user referenced from a dashboard usage record (author or viewer). | | author | handle | string | Datadog handle (login) of the user. | | author | id | string | The user ID. | | author | is_disabled | boolean | Whether the user account is disabled. | | author | name | string | Display name of the user. | | attributes | created_at | date-time | When the dashboard was created. | | attributes | 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. | | attributes | edited_at | date-time | When the dashboard was most recently edited. | | attributes | org_id [*required*] | int64 | The Datadog organization that owns the dashboard. | | attributes | teams | [string] | Teams the dashboard is tagged with. | | attributes | title | string | The dashboard title. | | attributes | total_views | int64 | Total view count for the dashboard. Counts only views captured by Real User Monitoring (RUM); `0` in orgs without RUM. | | attributes | 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. | | additionalProperties | | int64 | View count for that view type. | | attributes | 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. | | attributes | viewer | object | A user referenced from a dashboard usage record (author or viewer). | | viewer | handle | string | Datadog handle (login) of the user. | | viewer | id | string | The user ID. | | viewer | is_disabled | boolean | Whether the user account is disabled. | | viewer | name | string | Display name of the user. | | attributes | widget_count | int64 | The total number of widgets on the dashboard. | | attributes | widget_count_by_type | object | Widget counts keyed by widget type. The map includes group widgets and widgets without requests. | | additionalProperties | | int64 | Widget count for that widget type. | | data | id [*required*] | string | The dashboard ID. | | data | type [*required*] | enum | The type of the resource. Always `dashboards-usages`. Allowed enum values: `dashboards-usages`. Default: `dashboards-usages`. | {% /tab %} {% tab label="Example" %} ```json { "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": { "": "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": { "": "integer" } }, "id": "q5j-nti-fv6", "type": "dashboards-usages" } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="404" %} Not Found {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Path parameters export dashboard_id="q5j-nti-fv6" # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/${dashboard_id}/usage" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% tab label="Go" %} ```go // Get usage stats for a dashboard returns "OK" response package main import ( "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" ) func main() { // there is a valid "dashboard" in the system DashboardID := 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) if err != 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) } ``` #### Instructions First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" go run "main.go" ``` {% /tab %} {% tab label="Java" %} ```java // Get usage stats for a dashboard 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.model.DashboardUsageResponse; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); defaultClient.setUnstableOperationEnabled("v2.getDashboardUsage", true); DashboardsApi apiInstance = new DashboardsApi(defaultClient); // there is a valid "dashboard" in the system String DASHBOARD_ID = System.getenv("DASHBOARD_ID"); try { DashboardUsageResponse result = apiInstance.getDashboardUsage(DASHBOARD_ID); System.out.println(result); } catch (ApiException e) { 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(); } } } ``` #### Instructions First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" java "Example.java" ``` {% /tab %} {% tab label="Python" %} ```python """ Get usage stats for a dashboard returns "OK" response """ from os import environ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.dashboards_api import DashboardsApi # there is a valid "dashboard" in the system DASHBOARD_ID = environ["DASHBOARD_ID"] configuration = Configuration() configuration.access_token = environ["DD_BEARER_TOKEN"] configuration.unstable_operations["get_dashboard_usage"] = True with ApiClient(configuration) as api_client: api_instance = DashboardsApi(api_client) response = api_instance.get_dashboard_usage( dashboard_id=DASHBOARD_ID, ) print(response) ``` #### Instructions First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" python3 "example.py" ``` {% /tab %} {% tab label="Ruby" %} ```ruby # Get usage stats for a dashboard returns "OK" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] config.unstable_operations["v2.get_dashboard_usage".to_sym] = true end api_instance = DatadogAPIClient::V2::DashboardsAPI.new # there is a valid "dashboard" in the system DASHBOARD_ID = ENV["DASHBOARD_ID"] p api_instance.get_dashboard_usage(DASHBOARD_ID) ``` #### Instructions First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" rb "example.rb" ``` {% /tab %} {% tab label="Rust" %} ```rust // Get usage stats for a dashboard returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_dashboards::DashboardsAPI; #[tokio::main] async fn main() { // there is a valid "dashboard" in the system let dashboard_id = std::env::var("DASHBOARD_ID").unwrap(); let mut configuration = datadog::Configuration::new(); configuration.set_unstable_operation_enabled("v2.get_dashboard_usage", true); let api = DashboardsAPI::with_config(configuration); let resp = api.get_dashboard_usage(dashboard_id.clone()).await; if let Ok(value) = resp { println!("{:#?}", value); } else { println!("{:#?}", resp.unwrap_err()); } } ``` #### Instructions First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: ```bash DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ``` {% /tab %} {% tab label="TypeScript" %} ```typescript /** * Get usage stats for a dashboard returns "OK" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration({ authMethods: { AuthZ: { accessToken: process.env.DD_BEARER_TOKEN as string, }, }, }); configuration.unstableOperations["v2.getDashboardUsage"] = true; const apiInstance = new v2.DashboardsApi(configuration); // there is a valid "dashboard" in the system const DASHBOARD_ID = process.env.DASHBOARD_ID as string; const params: 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)); ``` #### Instructions First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" tsc "example.ts" ``` {% /tab %} {% /tabs %}