--- title: Get usage stats for all dashboards description: Get paginated usage statistics for every dashboard in the caller's organization. breadcrumbs: Documentation > API > Get usage stats for all dashboards --- > For the complete documentation index, see [llms.txt](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/llms.txt). # Get usage stats for all dashboards ## 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/usage | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/dashboards/usage | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/dashboards/usage | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/dashboards/usage | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/dashboards/usage | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/dashboards/usage | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/dashboards/usage | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/dashboards/usage | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/dashboards/usage | ### Overview 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. This endpoint requires the `dashboards_read` permission. OAuth apps require the `dashboards_read` authorization [scope](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/fr/api/latest/scopes.md#dashboards) to access this endpoint. ### Arguments #### Query Strings | Field | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page[limit] | integer | Maximum number of dashboards to return per page. Server-side maximum is 500; values above 500 return a 400 Bad Request. Default: `250`. | | page[offset] | integer | Zero-based offset into the result set. Default: `0`. | | 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. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Paginated list of dashboard usage records. | Parent field | Field | Type | Description | | -------------------- | ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | Dashboard usage records, one per dashboard in the caller's organization. | | 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`. | | | links | object | Pagination links for a list of dashboard usage records. | | links | first | string | Link to the first page. | | links | last | string | Link to the last page, or `null` if the total is unknown. | | links | next | string | Link to the next page. Absent when there is no next page. | | links | prev | string | Link to the previous page. Absent when there is no previous page. | | links | self | string | Link to the current page. | | | meta [*required*] | object | Pagination metadata for a list of dashboard usage records. | | meta | page | object | Offset-based pagination schema. | | page | first_offset | int64 | Integer representing the offset to fetch the first page of results. | | page | last_offset | int64 | Integer representing the offset to fetch the last page of results. | | page | limit | int64 | Integer representing the number of elements to be returned in the results. | | page | next_offset | int64 | Integer representing the index of the first element in the next page of results. Equal to page size added to the current offset. | | page | offset | int64 | Integer representing the index of the first element in the results. | | page | prev_offset | int64 | Integer representing the index of the first element in the previous page of results. | | page | total | int64 | Integer representing the total number of elements available. | | page | type | enum | The pagination type used for offset-based pagination. Allowed enum values: `offset_limit`. Default: `offset_limit`. | {% /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" } ], "links": { "first": "https://api.datadoghq.com/api/v2/dashboards/usage?page[offset]=0&page[limit]=250", "last": "string", "next": "string", "prev": "string", "self": "https://api.datadoghq.com/api/v2/dashboards/usage" }, "meta": { "page": { "first_offset": 0, "last_offset": 900, "limit": 100, "next_offset": 100, "offset": 0, "prev_offset": 100, "total": 1000, "type": "offset_limit" } } } ``` {% /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="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 # 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/usage" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% tab label="Go" %} ```go // Get usage stats for all dashboards 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() { ctx := datadog.NewDefaultContext(context.Background()) ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN")) configuration := datadog.NewConfiguration() configuration.SetUnstableOperationEnabled("v2.ListDashboardsUsage", true) apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewDashboardsApi(apiClient) resp, r, err := api.ListDashboardsUsage(ctx, *datadogV2.NewListDashboardsUsageOptionalParameters()) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `DashboardsApi.ListDashboardsUsage`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `DashboardsApi.ListDashboardsUsage`:\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 all dashboards 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.ListDashboardsUsageResponse; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); defaultClient.setUnstableOperationEnabled("v2.listDashboardsUsage", true); DashboardsApi apiInstance = new DashboardsApi(defaultClient); try { ListDashboardsUsageResponse result = apiInstance.listDashboardsUsage(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling DashboardsApi#listDashboardsUsage"); 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 all dashboards returns "OK" response """ from os import environ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.dashboards_api import DashboardsApi configuration = Configuration() configuration.access_token = environ["DD_BEARER_TOKEN"] configuration.unstable_operations["list_dashboards_usage"] = True with ApiClient(configuration) as api_client: api_instance = DashboardsApi(api_client) response = api_instance.list_dashboards_usage() 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 all dashboards returns "OK" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] config.unstable_operations["v2.list_dashboards_usage".to_sym] = true end api_instance = DatadogAPIClient::V2::DashboardsAPI.new p api_instance.list_dashboards_usage() ``` #### 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 all dashboards returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_dashboards::DashboardsAPI; use datadog_api_client::datadogV2::api_dashboards::ListDashboardsUsageOptionalParams; #[tokio::main] async fn main() { let mut configuration = datadog::Configuration::new(); configuration.set_unstable_operation_enabled("v2.list_dashboards_usage", true); let api = DashboardsAPI::with_config(configuration); let resp = api .list_dashboards_usage(ListDashboardsUsageOptionalParams::default()) .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 all dashboards 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.listDashboardsUsage"] = true; const apiInstance = new v2.DashboardsApi(configuration); apiInstance .listDashboardsUsage() .then((data: v2.ListDashboardsUsageResponse) => { 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 %}