Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED US2-FED

Widgets

Create, read, update, and delete saved widgets. Widgets are reusable visualization components stored independently from any dashboard or notebook, partitioned by experience type and identified by a UUID.

Create a widget

POST https://api.ap1.datadoghq.com/api/v2/widgets/{experience_type}https://api.ap2.datadoghq.com/api/v2/widgets/{experience_type}https://api.datadoghq.eu/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}https://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}

Overview

Create a new widget for a given experience type. This endpoint requires any of the following permissions:

  • cloud_cost_management_write
  • generate_log_reports
  • manage_log_reports
  • product_analytics_saved_widgets_write

    • Arguments

    Path Parameters

    Name

    Type

    Description

    experience_type [required]

    string

    The experience type for the widget.

    Request

    Body Data (required)

    Widget request body. The definition object’s required fields vary by widget.definition.type: every type requires requests, and some types require additional fields (e.g. cloud_cost_summary requires graph_options, geomap requires style and view). The example below shows a complete cloud_cost_summary payload for the ccm_reports experience type.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Data for creating or updating a widget.

    attributes [required]

    object

    Attributes for creating or updating a widget.

    definition [required]

    object

    The definition of a widget, including its type and configuration.

    title [required]

    string

    The display title of the widget.

    type [required]

    enum

    Widget types that are allowed to be stored as individual records. This is not a complete list of dashboard and notebook widget types. Allowed enum values: bar_chart,change,cloud_cost_summary,cohort,funnel,geomap,list_stream,query_table,query_value,retention_curve

    Show 5 more,sankey,sunburst,timeseries,toplist,treemap

    tags

    [string]

    User-defined tags for organizing the widget.

    type [required]

    string

    Widgets resource type.

    {
  "data": {
    "attributes": {
      "definition": {
        "title": "My Widget",
        "type": "bar_chart"
      },
      "tags": []
    },
    "type": "widgets"
  }
}

    Response

    OK

    Response containing a single widget.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A widget resource object.

    attributes [required]

    object

    Attributes of a widget resource.

    created_at [required]

    string

    ISO 8601 timestamp of when the widget was created.

    definition [required]

    object

    The definition of a widget, including its type and configuration.

    title [required]

    string

    The display title of the widget.

    type [required]

    enum

    Widget types that are allowed to be stored as individual records. This is not a complete list of dashboard and notebook widget types. Allowed enum values: bar_chart,change,cloud_cost_summary,cohort,funnel,geomap,list_stream,query_table,query_value,retention_curve

    Show 5 more,sankey,sunburst,timeseries,toplist,treemap

    is_favorited [required]

    boolean

    Whether the current user has favorited this widget. Populated on get, batch_get, update, and search responses; create responses always return false because a widget can only be favorited after it exists. Favoriting itself is performed through the shared favorites API, not this service.

    modified_at [required]

    string

    ISO 8601 timestamp of when the widget was last modified.

    tags [required]

    [string]

    User-defined tags for organizing widgets.

    id [required]

    string

    The unique identifier of the widget.

    relationships

    object

    Relationships of the widget resource.

    created_by

    object

    The user who created the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    modified_by

    object

    The user who last modified the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    type [required]

    string

    Widgets resource type.

    included

    [object]

    Array of user resources related to the widget.

    attributes

    object

    Attributes of an included user resource.

    handle

    string

    The email handle of the user.

    name

    string

    The display name of the user.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    {
  "data": {
    "attributes": {
      "created_at": "2024-01-15T00:00:00.000Z",
      "definition": {
        "title": "My Widget",
        "type": "bar_chart"
      },
      "is_favorited": false,
      "modified_at": "2024-01-15T00:00:00.000Z",
      "tags": [
        "team:my-team"
      ]
    },
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "relationships": {
      "created_by": {
        "data": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "type": "users"
        }
      },
      "modified_by": {
        "data": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "type": "users"
        }
      }
    },
    "type": "widgets"
  },
  "included": [
    {
      "attributes": {
        "handle": "john.doe@example.com",
        "name": "John Doe"
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "users"
    }
  ]
}

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

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

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

    Code Example

                      ## CCM cost summary widget
# 

    # Path parameters
    export experience_type="ccm_reports"
    # Curl command
    curl -X POST "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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "definition": {
        "graph_options": [
          {
            "type": "query_value",
            "view": "total"
          },
          {
            "type": "query_value",
            "view": "change"
          },
          {
            "display_type": "bars",
            "type": "timeseries"
          },
          {
            "type": "cloud_cost_table",
            "view": "summary"
          }
        ],
        "requests": [
          {
            "formulas": [
              {
                "formula": "query1"
              }
            ],
            "queries": [
              {
                "data_source": "cloud_cost",
                "name": "query1",
                "query": "sum:aws.cost.amortized{*} by {aws_product}.rollup(sum, daily)"
              }
            ],
            "response_format": "timeseries"
          }
        ],
        "time": {
          "type": "live",
          "unit": "day",
          "value": 30
        },
        "title": "AWS spend by service (last 30 days)",
        "type": "cloud_cost_summary"
      },
      "tags": [
        "finops",
        "aws"
      ]
    },
    "type": "widgets"
  }
}
EOF

    Get a widget

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

    Overview

    Retrieve a widget by its UUID for a given experience type. 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]

    string

    The experience type for the widget.

    uuid [required]

    string

    The UUID of the widget.

    Response

    OK

    Response containing a single widget.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A widget resource object.

    attributes [required]

    object

    Attributes of a widget resource.

    created_at [required]

    string

    ISO 8601 timestamp of when the widget was created.

    definition [required]

    object

    The definition of a widget, including its type and configuration.

    title [required]

    string

    The display title of the widget.

    type [required]

    enum

    Widget types that are allowed to be stored as individual records. This is not a complete list of dashboard and notebook widget types. Allowed enum values: bar_chart,change,cloud_cost_summary,cohort,funnel,geomap,list_stream,query_table,query_value,retention_curve

    Show 5 more,sankey,sunburst,timeseries,toplist,treemap

    is_favorited [required]

    boolean

    Whether the current user has favorited this widget. Populated on get, batch_get, update, and search responses; create responses always return false because a widget can only be favorited after it exists. Favoriting itself is performed through the shared favorites API, not this service.

    modified_at [required]

    string

    ISO 8601 timestamp of when the widget was last modified.

    tags [required]

    [string]

    User-defined tags for organizing widgets.

    id [required]

    string

    The unique identifier of the widget.

    relationships

    object

    Relationships of the widget resource.

    created_by

    object

    The user who created the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    modified_by

    object

    The user who last modified the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    type [required]

    string

    Widgets resource type.

    included

    [object]

    Array of user resources related to the widget.

    attributes

    object

    Attributes of an included user resource.

    handle

    string

    The email handle of the user.

    name

    string

    The display name of the user.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    {
  "data": {
    "attributes": {
      "created_at": "2024-01-15T00:00:00.000Z",
      "definition": {
        "title": "My Widget",
        "type": "bar_chart"
      },
      "is_favorited": false,
      "modified_at": "2024-01-15T00:00:00.000Z",
      "tags": [
        "team:my-team"
      ]
    },
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "relationships": {
      "created_by": {
        "data": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "type": "users"
        }
      },
      "modified_by": {
        "data": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "type": "users"
        }
      }
    },
    "type": "widgets"
  },
  "included": [
    {
      "attributes": {
        "handle": "john.doe@example.com",
        "name": "John Doe"
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "users"
    }
  ]
}

    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 experience_type="ccm_reports"
    export uuid="CHANGE_ME"
    # 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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/widgets/${experience_type}/${uuid}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Update a widget

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

    Overview

    Update a widget by its UUID for a given experience type. This performs a full replacement of the widget definition. This endpoint requires any of the following permissions:

  • cloud_cost_management_write
  • generate_log_reports
  • manage_log_reports
  • product_analytics_saved_widgets_write

    • Arguments

    Path Parameters

    Name

    Type

    Description

    experience_type [required]

    string

    The experience type for the widget.

    uuid [required]

    string

    The UUID of the widget.

    Request

    Body Data (required)

    Widget request body. The definition object’s required fields vary by widget.definition.type; see CreateWidget above for a complete worked payload. Update is a full replacement of the widget definition.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Data for creating or updating a widget.

    attributes [required]

    object

    Attributes for creating or updating a widget.

    definition [required]

    object

    The definition of a widget, including its type and configuration.

    title [required]

    string

    The display title of the widget.

    type [required]

    enum

    Widget types that are allowed to be stored as individual records. This is not a complete list of dashboard and notebook widget types. Allowed enum values: bar_chart,change,cloud_cost_summary,cohort,funnel,geomap,list_stream,query_table,query_value,retention_curve

    Show 5 more,sankey,sunburst,timeseries,toplist,treemap

    tags

    [string]

    User-defined tags for organizing the widget.

    type [required]

    string

    Widgets resource type.

    {
  "data": {
    "attributes": {
      "definition": {
        "title": "My Widget",
        "type": "bar_chart"
      },
      "tags": []
    },
    "type": "widgets"
  }
}

    Response

    OK

    Response containing a single widget.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A widget resource object.

    attributes [required]

    object

    Attributes of a widget resource.

    created_at [required]

    string

    ISO 8601 timestamp of when the widget was created.

    definition [required]

    object

    The definition of a widget, including its type and configuration.

    title [required]

    string

    The display title of the widget.

    type [required]

    enum

    Widget types that are allowed to be stored as individual records. This is not a complete list of dashboard and notebook widget types. Allowed enum values: bar_chart,change,cloud_cost_summary,cohort,funnel,geomap,list_stream,query_table,query_value,retention_curve

    Show 5 more,sankey,sunburst,timeseries,toplist,treemap

    is_favorited [required]

    boolean

    Whether the current user has favorited this widget. Populated on get, batch_get, update, and search responses; create responses always return false because a widget can only be favorited after it exists. Favoriting itself is performed through the shared favorites API, not this service.

    modified_at [required]

    string

    ISO 8601 timestamp of when the widget was last modified.

    tags [required]

    [string]

    User-defined tags for organizing widgets.

    id [required]

    string

    The unique identifier of the widget.

    relationships

    object

    Relationships of the widget resource.

    created_by

    object

    The user who created the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    modified_by

    object

    The user who last modified the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    type [required]

    string

    Widgets resource type.

    included

    [object]

    Array of user resources related to the widget.

    attributes

    object

    Attributes of an included user resource.

    handle

    string

    The email handle of the user.

    name

    string

    The display name of the user.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    {
  "data": {
    "attributes": {
      "created_at": "2024-01-15T00:00:00.000Z",
      "definition": {
        "title": "My Widget",
        "type": "bar_chart"
      },
      "is_favorited": false,
      "modified_at": "2024-01-15T00:00:00.000Z",
      "tags": [
        "team:my-team"
      ]
    },
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "relationships": {
      "created_by": {
        "data": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "type": "users"
        }
      },
      "modified_by": {
        "data": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "type": "users"
        }
      }
    },
    "type": "widgets"
  },
  "included": [
    {
      "attributes": {
        "handle": "john.doe@example.com",
        "name": "John Doe"
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "users"
    }
  ]
}

    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

                      ## CCM cost summary widget
# 

    # Path parameters
    export experience_type="ccm_reports"
    export uuid="CHANGE_ME"
    # Curl command
    curl -X PUT "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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/widgets/${experience_type}/${uuid}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "definition": {
        "graph_options": [
          {
            "type": "query_value",
            "view": "total"
          },
          {
            "type": "query_value",
            "view": "change"
          },
          {
            "display_type": "bars",
            "type": "timeseries"
          },
          {
            "type": "cloud_cost_table",
            "view": "summary"
          }
        ],
        "requests": [
          {
            "formulas": [
              {
                "formula": "query1"
              }
            ],
            "queries": [
              {
                "data_source": "cloud_cost",
                "name": "query1",
                "query": "sum:aws.cost.amortized{*} by {aws_product}.rollup(sum, daily)"
              }
            ],
            "response_format": "timeseries"
          }
        ],
        "time": {
          "type": "live",
          "unit": "day",
          "value": 30
        },
        "title": "AWS spend by service (last 30 days)",
        "type": "cloud_cost_summary"
      },
      "tags": [
        "finops",
        "aws"
      ]
    },
    "type": "widgets"
  }
}
EOF

    Delete a widget

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

    Overview

    Soft-delete a widget by its UUID for a given experience type. This endpoint requires any of the following permissions:

  • cloud_cost_management_write
  • generate_log_reports
  • manage_log_reports
  • product_analytics_saved_widgets_write

    • Arguments

    Path Parameters

    Name

    Type

    Description

    experience_type [required]

    string

    The experience type for the widget.

    uuid [required]

    string

    The UUID of the widget.

    Response

    No Content

    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 experience_type="ccm_reports"
    export uuid="CHANGE_ME"
    # Curl command
    curl -X DELETE "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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/widgets/${experience_type}/${uuid}" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Search widgets

    GET https://api.ap1.datadoghq.com/api/v2/widgets/{experience_type}https://api.ap2.datadoghq.com/api/v2/widgets/{experience_type}https://api.datadoghq.eu/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}https://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}

    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]

    string

    The experience type for the widget.

    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 more, sankey, 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.

    page[number]

    integer

    Page number for pagination (0-indexed).

    page[size]

    integer

    Number of widgets per page.

    Response

    OK

    Response containing a list of widgets.

    Expand All

    Field

    Type

    Description

    data [required]

    [object]

    List of widget resources.

    attributes [required]

    object

    Attributes of a widget resource.

    created_at [required]

    string

    ISO 8601 timestamp of when the widget was created.

    definition [required]

    object

    The definition of a widget, including its type and configuration.

    title [required]

    string

    The display title of the widget.

    type [required]

    enum

    Widget types that are allowed to be stored as individual records. This is not a complete list of dashboard and notebook widget types. Allowed enum values: bar_chart,change,cloud_cost_summary,cohort,funnel,geomap,list_stream,query_table,query_value,retention_curve

    Show 5 more,sankey,sunburst,timeseries,toplist,treemap

    is_favorited [required]

    boolean

    Whether the current user has favorited this widget. Populated on get, batch_get, update, and search responses; create responses always return false because a widget can only be favorited after it exists. Favoriting itself is performed through the shared favorites API, not this service.

    modified_at [required]

    string

    ISO 8601 timestamp of when the widget was last modified.

    tags [required]

    [string]

    User-defined tags for organizing widgets.

    id [required]

    string

    The unique identifier of the widget.

    relationships

    object

    Relationships of the widget resource.

    created_by

    object

    The user who created the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    modified_by

    object

    The user who last modified the widget.

    data

    object

    Relationship data referencing a user resource.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    type [required]

    string

    Widgets resource type.

    included

    [object]

    Array of user resources related to the widgets.

    attributes

    object

    Attributes of an included user resource.

    handle

    string

    The email handle of the user.

    name

    string

    The display name of the user.

    id [required]

    string

    The unique identifier of the user.

    type [required]

    string

    Users resource type.

    meta

    object

    Metadata about the search results.

    created_by_anyone_total

    int64

    Total number of widgets created by anyone.

    created_by_you_total

    int64

    Total number of widgets created by the current user.

    favorited_by_you_total

    int64

    Total number of widgets favorited by the current user.

    filtered_total

    int64

    Total number of widgets matching the current filter criteria.

    {
  "data": [
    {
      "attributes": {
        "created_at": "2024-01-15T00:00:00.000Z",
        "definition": {
          "title": "My Widget",
          "type": "bar_chart"
        },
        "is_favorited": false,
        "modified_at": "2024-01-15T00:00:00.000Z",
        "tags": [
          "team:my-team"
        ]
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "relationships": {
        "created_by": {
          "data": {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "type": "users"
          }
        },
        "modified_by": {
          "data": {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "type": "users"
          }
        }
      },
      "type": "widgets"
    }
  ],
  "included": [
    {
      "attributes": {
        "handle": "john.doe@example.com",
        "name": "John Doe"
      },
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "users"
    }
  ],
  "meta": {
    "created_by_anyone_total": "integer",
    "created_by_you_total": "integer",
    "favorited_by_you_total": "integer",
    "filtered_total": "integer"
  }
}

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

    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 experience_type="ccm_reports"
    # 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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/widgets/${experience_type}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"