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": "[email protected]",
            "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
    """
    Create a widget 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.create_or_update_widget_request import CreateOrUpdateWidgetRequest
    from datadog_api_client.v2.model.create_or_update_widget_request_attributes import CreateOrUpdateWidgetRequestAttributes
    from datadog_api_client.v2.model.create_or_update_widget_request_data import CreateOrUpdateWidgetRequestData
    from datadog_api_client.v2.model.widget_definition import WidgetDefinition
    from datadog_api_client.v2.model.widget_experience_type import WidgetExperienceType
    from datadog_api_client.v2.model.widget_type import WidgetType
    
    body = CreateOrUpdateWidgetRequest(
        data=CreateOrUpdateWidgetRequestData(
            attributes=CreateOrUpdateWidgetRequestAttributes(
                definition=WidgetDefinition(
                    title="My Widget",
                    type=WidgetType.BAR_CHART,
                ),
                tags=[],
            ),
            type="widgets",
        ),
    )
    
    configuration = Configuration()
    with ApiClient(configuration) as api_client:
        api_instance = WidgetsApi(api_client)
        response = api_instance.create_widget(experience_type=WidgetExperienceType.CCM_REPORTS, body=body)
    
        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"
    # Create a widget returns "OK" response
    
    require "datadog_api_client"
    api_instance = DatadogAPIClient::V2::WidgetsAPI.new
    
    body = DatadogAPIClient::V2::CreateOrUpdateWidgetRequest.new({
      data: DatadogAPIClient::V2::CreateOrUpdateWidgetRequestData.new({
        attributes: DatadogAPIClient::V2::CreateOrUpdateWidgetRequestAttributes.new({
          definition: DatadogAPIClient::V2::WidgetDefinition.new({
            title: "My Widget",
            type: DatadogAPIClient::V2::WidgetType::BAR_CHART,
          }),
          tags: [],
        }),
        type: "widgets",
      }),
    })
    p api_instance.create_widget(WidgetExperienceType::CCM_REPORTS, body)
    

    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"
    // Create a widget 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() {
    	body := datadogV2.CreateOrUpdateWidgetRequest{
    		Data: datadogV2.CreateOrUpdateWidgetRequestData{
    			Attributes: datadogV2.CreateOrUpdateWidgetRequestAttributes{
    				Definition: datadogV2.WidgetDefinition{
    					Title: "My Widget",
    					Type:  datadogV2.WIDGETTYPE_BAR_CHART,
    				},
    				Tags: *datadog.NewNullableList(&[]string{}),
    			},
    			Type: "widgets",
    		},
    	}
    	ctx := datadog.NewDefaultContext(context.Background())
    	configuration := datadog.NewConfiguration()
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewWidgetsApi(apiClient)
    	resp, r, err := api.CreateWidget(ctx, datadogV2.WIDGETEXPERIENCETYPE_CCM_REPORTS, body)
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `WidgetsApi.CreateWidget`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `WidgetsApi.CreateWidget`:\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"
    // Create a widget 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.CreateOrUpdateWidgetRequest;
    import com.datadog.api.client.v2.model.CreateOrUpdateWidgetRequestAttributes;
    import com.datadog.api.client.v2.model.CreateOrUpdateWidgetRequestData;
    import com.datadog.api.client.v2.model.WidgetDefinition;
    import com.datadog.api.client.v2.model.WidgetExperienceType;
    import com.datadog.api.client.v2.model.WidgetResponse;
    import com.datadog.api.client.v2.model.WidgetType;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        WidgetsApi apiInstance = new WidgetsApi(defaultClient);
    
        CreateOrUpdateWidgetRequest body =
            new CreateOrUpdateWidgetRequest()
                .data(
                    new CreateOrUpdateWidgetRequestData()
                        .attributes(
                            new CreateOrUpdateWidgetRequestAttributes()
                                .definition(
                                    new WidgetDefinition()
                                        .title("My Widget")
                                        .type(WidgetType.BAR_CHART)))
                        .type("widgets"));
    
        try {
          WidgetResponse result = apiInstance.createWidget(WidgetExperienceType.CCM_REPORTS, body);
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling WidgetsApi#createWidget");
          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"
    // Create a widget returns "OK" response
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_widgets::WidgetsAPI;
    use datadog_api_client::datadogV2::model::CreateOrUpdateWidgetRequest;
    use datadog_api_client::datadogV2::model::CreateOrUpdateWidgetRequestAttributes;
    use datadog_api_client::datadogV2::model::CreateOrUpdateWidgetRequestData;
    use datadog_api_client::datadogV2::model::WidgetDefinition;
    use datadog_api_client::datadogV2::model::WidgetExperienceType;
    use datadog_api_client::datadogV2::model::WidgetType;
    
    #[tokio::main]
    async fn main() {
        let body = CreateOrUpdateWidgetRequest::new(CreateOrUpdateWidgetRequestData::new(
            CreateOrUpdateWidgetRequestAttributes::new(WidgetDefinition::new(
                "My Widget".to_string(),
                WidgetType::BAR_CHART,
            ))
            .tags(Some(vec![])),
            "widgets".to_string(),
        ));
        let configuration = datadog::Configuration::new();
        let api = WidgetsAPI::with_config(configuration);
        let resp = api
            .create_widget(WidgetExperienceType::CCM_REPORTS, body)
            .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
    /**
     * Create a widget returns "OK" response
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    const apiInstance = new v2.WidgetsApi(configuration);
    
    const params: v2.WidgetsApiCreateWidgetRequest = {
      body: {
        data: {
          attributes: {
            definition: {
              title: "My Widget",
              type: "bar_chart",
            },
            tags: [],
          },
          type: "widgets",
        },
      },
      experienceType: "ccm_reports",
    };
    
    apiInstance
      .createWidget(params)
      .then((data: v2.WidgetResponse) => {
        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"