Language

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

Datadog Site

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

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}"
    
                
    """
Search widgets returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.widgets_api import WidgetsApi
from datadog_api_client.v2.model.widget_experience_type import WidgetExperienceType

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = WidgetsApi(api_client)
    response = api_instance.search_widgets(
        experience_type=WidgetExperienceType.CCM_REPORTS,
    )

    print(response)

    Instructions

    First install the library and its dependencies and then save the example to example.py and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
    # Search widgets returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::WidgetsAPI.new
p api_instance.search_widgets(WidgetExperienceType::CCM_REPORTS)

    Instructions

    First install the library and its dependencies and then save the example to example.rb and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
    // Search widgets 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())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewWidgetsApi(apiClient)
	resp, r, err := api.SearchWidgets(ctx, datadogV2.WIDGETEXPERIENCETYPE_CCM_REPORTS, *datadogV2.NewSearchWidgetsOptionalParameters())

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `WidgetsApi.SearchWidgets`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `WidgetsApi.SearchWidgets`:\n%s\n", responseContent)
}

    Instructions

    First install the library and its dependencies and then save the example to main.go and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
    // Search widgets returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.WidgetsApi;
import com.datadog.api.client.v2.model.WidgetExperienceType;
import com.datadog.api.client.v2.model.WidgetListResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    WidgetsApi apiInstance = new WidgetsApi(defaultClient);

    try {
      WidgetListResponse result = apiInstance.searchWidgets(WidgetExperienceType.CCM_REPORTS);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling WidgetsApi#searchWidgets");
      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 and then save the example to Example.java and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
    // Search widgets returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_widgets::SearchWidgetsOptionalParams;
use datadog_api_client::datadogV2::api_widgets::WidgetsAPI;
use datadog_api_client::datadogV2::model::WidgetExperienceType;

#[tokio::main]
async fn main() {
    let configuration = datadog::Configuration::new();
    let api = WidgetsAPI::with_config(configuration);
    let resp = api
        .search_widgets(
            WidgetExperienceType::CCM_REPORTS,
            SearchWidgetsOptionalParams::default(),
        )
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

    Instructions

    First install the library and its dependencies and then save the example to src/main.rs and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
    /**
 * Search widgets returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v2.WidgetsApi(configuration);

const params: v2.WidgetsApiSearchWidgetsRequest = {
  experienceType: "ccm_reports",
};

apiInstance
  .searchWidgets(params)
  .then((data: v2.WidgetListResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

    Instructions

    First install the library and its dependencies and then save the example to example.ts and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"