For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/dashboards/get-usage-stats-for-all-dashboards.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

Get usage stats for all dashboards

WARNINGNote: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.
GEThttps://api.datadoghq.com/api/v2/dashboards/usagehttps://api.us3.datadoghq.com/api/v2/dashboards/usagehttps://api.us5.datadoghq.com/api/v2/dashboards/usagehttps://api.datadoghq.eu/api/v2/dashboards/usagehttps://api.ap1.datadoghq.com/api/v2/dashboards/usagehttps://api.ap2.datadoghq.com/api/v2/dashboards/usagehttps://api.uk1.datadoghq.com/api/v2/dashboards/usagehttps://api.ddog-gov.com/api/v2/dashboards/usagehttps://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 to access this endpoint.

Arguments

Query Strings

Name
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

OK

Paginated list of dashboard usage records.

Field
Type
Description
data [required]
[object]

Dashboard usage records, one per dashboard in the caller's organization.

links
object

Pagination links for a list of dashboard usage records.

meta [required]
object

Pagination metadata for a list of dashboard usage records.

Code Example

Get usage stats for all dashboards
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/dashboards/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"