For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/stefon.simmons/docs-astro-web-10435/api/latest/widgets/search-widgets.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

Search widgets

GEThttps://api.datadoghq.com/api/v2/widgets/{experience_type}https://api.us3.datadoghq.com/api/v2/widgets/{experience_type}https://api.us5.datadoghq.com/api/v2/widgets/{experience_type}https://api.datadoghq.eu/api/v2/widgets/{experience_type}https://api.ap1.datadoghq.com/api/v2/widgets/{experience_type}https://api.ap2.datadoghq.com/api/v2/widgets/{experience_type}https://api.uk1.datadoghq.com/api/v2/widgets/{experience_type}https://api.ddog-gov.com/api/v2/widgets/{experience_type}https://api.us2.ddog-gov.com/api/v2/widgets/{experience_type}

Overview

Search and list widgets for a given experience type, with filtering, sorting, and pagination.

Response meta carries totals scoped to the current filter:

  • filtered_total — widgets matching the filter.
  • created_by_you_total — among the matches, how many the current user created.
  • favorited_by_you_total — among the matches, how many the current user has favorited.
  • created_by_anyone_total — total widgets in the experience type, ignoring filters.

Each returned widget includes is_favorited reflecting the current user's favorite status. Favoriting itself is performed through the shared favorites API, not this endpoint.

This endpoint requires any of the following permissions:

  • cloud_cost_management_read
  • generate_log_reports
  • manage_log_reports
  • product_analytics_saved_widgets_read

Arguments

Path Parameters

Name
Type
Description
experience_type [required]
enum

The experience type for the widget.

Allowed enum values: ccm_reports, logs_reports, csv_reports, product_analytics

Query Strings

Name
Type
Description
filter[widgetType]
enum

Filter widgets by widget type.

Allowed enum values: bar_chart, change, cloud_cost_summary, cohort, funnel, geomap, list_stream, query_table, query_value, retention_curve
Show 5 moresankey, sunburst, timeseries, toplist, treemap
filter[creatorHandle]
string

Filter widgets by the email handle of the creator.

filter[isFavorited]
boolean

Filter to only widgets favorited by the current user.

filter[title]
string

Filter widgets by title (substring match).

filter[tags]
string

Filter widgets by tags. Format as bracket-delimited CSV, e.g. [tag1,tag2].

sort
string

Sort field for the results.

title, created_at, modified_at — both ascending and descending are supported. Use the bare field name for ascending (e.g. sort=title) or prefix with - for descending (e.g. sort=-modified_at).

is_favorited — returns favorites-first ordering (favorited widgets first, then the rest). Direction is fixed; the - prefix is ignored for this field.

Default: -modified_at
page[number]
integer

Page number for pagination (0-indexed).

Default: 0
page[size]
integer

Number of widgets per page.

Default: 50

Response

OK

Response containing a list of widgets.

Field
Type
Description
data [required]
[object]

List of widget resources.

included
[object]

Array of user resources related to the widgets.

meta
object

Metadata about the search results.

Code Example

Search widgets
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export experience_type="ccm_reports"

# 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/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"