widgets

Creates, updates, deletes, gets or lists a widgets resource.

Overview

Name	widgets
Type	Resource
Id	datadog.dashboards.widgets

Fields

The following fields are returned by SELECT queries:

get_widget

Name	Datatype	Description
id	string	The unique identifier of the widget. (example: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
attributes	object	Attributes of a widget resource.
relationships	object	Relationships of the widget resource.
type	string	Widgets resource type. (example: widgets)

search_widgets

Name	Datatype	Description
id	string	The unique identifier of the widget. (example: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
attributes	object	Attributes of a widget resource.
relationships	object	Relationships of the widget resource.
type	string	Widgets resource type. (example: widgets)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_widget	select	experience_type, uuid		Retrieve a widget by its UUID for a given experience type.
search_widgets	select	experience_type	filter[widget_type], filter[creator_handle], filter[is_favorited], filter[title], filter[tags], sort, page[number], page[size]	Search and list widgets for a given experience type, with filtering, sorting, and pagination.<br /><br />Response meta carries totals scoped to the current filter:<br />- filtered_total — widgets matching the filter.<br />- created_by_you_total — among the matches, how many the current user created.<br />- favorited_by_you_total — among the matches, how many the current user has favorited.<br />- created_by_anyone_total — total widgets in the experience type, ignoring filters.<br /><br />Each returned widget includes is_favorited reflecting the current user's favorite status.<br />Favoriting itself is performed through the shared favorites API, not this endpoint.
create_widget	insert	experience_type, data		Create a new widget for a given experience type.
update_widget	replace	experience_type, uuid, data		Update a widget by its UUID for a given experience type. This performs a full replacement of the widget definition.
delete_widget	delete	experience_type, uuid		Soft-delete a widget by its UUID for a given experience type.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
experience_type	string	The experience type for the widget.
site	string	The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both.
uuid	string (uuid)	The UUID of the widget.
filter[creator_handle]	string	Filter widgets by the email handle of the creator. (wire: filter[creatorHandle])
filter[is_favorited]	boolean	Filter to only widgets favorited by the current user. (wire: filter[isFavorited])
filter[tags]	string	Filter widgets by tags. Format as bracket-delimited CSV, e.g. [tag1,tag2].
filter[title]	string	Filter widgets by title (substring match).
filter[widget_type]	string	Filter widgets by widget type. (wire: filter[widgetType])
page[number]	integer (int64)	Page number for pagination (0-indexed).
page[size]	integer (int64)	Number of widgets per page.
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.

SELECT examples

get_widget

Retrieve a widget by its UUID for a given experience type.

SELECT
id,
attributes,
relationships,
type
FROM datadog.dashboards.widgets
WHERE experience_type = '{{ experience_type }}' -- required
AND uuid = '{{ uuid }}' -- required
;

search_widgets

Search and list widgets for a given experience type, with filtering, sorting, and pagination.<br /><br />Response meta carries totals scoped to the current filter:<br />- filtered_total — widgets matching the filter.<br />- created_by_you_total — among the matches, how many the current user created.<br />- favorited_by_you_total — among the matches, how many the current user has favorited.<br />- created_by_anyone_total — total widgets in the experience type, ignoring filters.<br /><br />Each returned widget includes is_favorited reflecting the current user's favorite status.<br />Favoriting itself is performed through the shared favorites API, not this endpoint.

SELECT
id,
attributes,
relationships,
type
FROM datadog.dashboards.widgets
WHERE experience_type = '{{ experience_type }}' -- required
AND filter[widget_type] = '{{ filter[widget_type] }}'
AND filter[creator_handle] = '{{ filter[creator_handle] }}'
AND filter[is_favorited] = '{{ filter[is_favorited] }}'
AND filter[title] = '{{ filter[title] }}'
AND filter[tags] = '{{ filter[tags] }}'
AND sort = '{{ sort }}'
AND page[number] = '{{ page[number] }}'
AND page[size] = '{{ page[size] }}'
;

INSERT examples

create_widget

Create a new widget for a given experience type.

INSERT INTO datadog.dashboards.widgets (
data,
experience_type
)
SELECT 
'{{ data }}' /* required */,
'{{ experience_type }}'
RETURNING
data,
included
;

Manifest

# Description fields are for documentation purposes
- name: widgets
props:
  - name: experience_type
    value: "{{ experience_type }}"
    description: Required parameter for the widgets resource.
  - name: data
    description: |
      Data for creating or updating a widget.
    value:
      attributes:
        definition:
          title: "{{ title }}"
          type: "{{ type }}"
        tags:
          - "{{ tags }}"
      type: "{{ type }}"

REPLACE examples

update_widget

Update a widget by its UUID for a given experience type. This performs a full replacement of the widget definition.

REPLACE datadog.dashboards.widgets
SET 
data = '{{ data }}'
WHERE 
experience_type = '{{ experience_type }}' --required
AND uuid = '{{ uuid }}' --required
AND data = '{{ data }}' --required
RETURNING
data,
included;

DELETE examples

delete_widget

Soft-delete a widget by its UUID for a given experience type.

DELETE FROM datadog.dashboards.widgets
WHERE experience_type = '{{ experience_type }}' --required
AND uuid = '{{ uuid }}' --required
;