For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/api/latest/dashboards/get-usage-stats-for-a-dashboard.md. A documentation index is available at /llms.txt.

Get usage stats for a dashboard

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.ap2.datadoghq.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.datadoghq.eu/api/v2/dashboards/{dashboard_id}/usagehttps://api.ddog-gov.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.us2.ddog-gov.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.uk1.datadoghq.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.datadoghq.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.us3.datadoghq.com/api/v2/dashboards/{dashboard_id}/usagehttps://api.us5.datadoghq.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 to access this endpoint.

Arguments

Path Parameters

Name

Type

Description

dashboard_id [required]

string

The ID of the dashboard.

Response

OK

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"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export dashboard_id="q5j-nti-fv6"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/dashboards/${dashboard_id}/usage" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}"
"""
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 and then save the example to example.py and run following commands:

    
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" 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 and then save the example to example.rb and run following commands:

    
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" 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 and then save the example to main.go and run following commands:

    
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" 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 and then save the example to Example.java and run following commands:

    
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
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 and then save the example to src/main.rs and run following commands:

    
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";

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 and then save the example to example.ts and run following commands:

    
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"