For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/api/latest/cloud-cost-management/search-cost-recommendations.md. A documentation index is available at /llms.txt.

Language

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

Datadog Site

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

Search cost recommendations

copy Copy pageCopied

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/v2/cost/recommendationshttps://api.ap2.datadoghq.com/api/v2/cost/recommendationshttps://api.datadoghq.eu/api/v2/cost/recommendationshttps://api.ddog-gov.com/api/v2/cost/recommendationshttps://api.us2.ddog-gov.com/api/v2/cost/recommendationshttps://api.uk1.datadoghq.com/api/v2/cost/recommendationshttps://api.datadoghq.com/api/v2/cost/recommendationshttps://api.us3.datadoghq.com/api/v2/cost/recommendationshttps://api.us5.datadoghq.com/api/v2/cost/recommendations

Overview

List cost recommendations matching a filter, with pagination and sorting.

OAuth apps require the cloud_cost_management_read authorization scope to access this endpoint.

Arguments

Query Strings

Name

Type

Description

page[size]

string

Number of results per page (1–10000).

page[token]

string

Pagination token from a previous response.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

JSON:API resource containing the cost recommendations filter. This legacy search contract uses the resource ID for the filter expression rather than as a persistent resource identifier.

attributes

object

Attributes used to filter and sort cost recommendations.

filter

string

Filter expression applied to the recommendations. When supplied, this attribute overrides data.id, including when empty. When omitted, data.id is used. If the resulting filter is empty, it defaults to *. Scope, view, and pagination still apply.

scope

enum

Recommendations scope. Defaults to ccm; use experiment for experimental recommendations or * for both. Allowed enum values: ccm,experiment,*

sort

[object]

Ordered list of sort clauses applied to the result set.

expression

string

Field to sort by (for example, @potential_daily_savings).

order

string

Sort direction, either ASC or DESC.

view

string

Active view name (for example, active, dismissed, open, in-progress, or completed).

id

string

Filter expression applied to the recommendations when attributes.filter is omitted. When supplied, attributes.filter overrides this value, including when empty. If the resulting filter is empty, it defaults to *. Scope, view, and pagination still apply.

type [required]

enum

Legacy JSON:API resource type required by the cost recommendations search decoder. Allowed enum values: recommendations_filter

default: recommendations_filter

{
  "data": {
    "attributes": {
      "filter": "@resource_table:aws_ec2_instance",
      "scope": "string",
      "sort": [
        {
          "expression": "string",
          "order": "string"
        }
      ],
      "view": "string"
    },
    "id": "string",
    "type": "recommendations_filter"
  }
}

Response

OK

A page of cost recommendations with pagination metadata.

Expand All

Field

Type

Description

data [required]

[object]

The list of cost recommendations on this page.

attributes

object

Attributes describing a single cost recommendation.

dd_resource_key

string

Datadog resource key identifying the recommended resource.

potential_daily_savings

object

Estimated daily savings if the recommendation is applied.

amount

double

Numeric amount of the potential daily savings.

currency

string

ISO 4217 currency code for the savings amount.

recommendation_type

string

The kind of recommendation (for example, terminate or rightsize).

resource_id

string

Cloud provider identifier of the resource.

resource_type

string

Resource type (for example, aws_ec2_instance).

tags

[string]

Tags attached to the recommended resource.

id

string

Unique identifier for the recommendation.

type [required]

enum

Recommendation resource type. Allowed enum values: recommendation

default: recommendation

meta

object

Top-level JSON:API meta object for paginated cost recommendation responses.

page

object

Pagination metadata for a page of cost recommendations.

filter

string

The filter expression that was applied to produce this page.

next_page_token

string

Opaque token used to fetch the next page; absent on the last page.

page_size

int32

Number of items returned in this page (1–10000).

page_token

string

Pagination token echoed back from the request.

{
  "data": [
    {
      "attributes": {
        "dd_resource_key": "string",
        "potential_daily_savings": {
          "amount": "number",
          "currency": "string"
        },
        "recommendation_type": "string",
        "resource_id": "string",
        "resource_type": "string",
        "tags": []
      },
      "id": "string",
      "type": "recommendation"
    }
  ],
  "meta": {
    "page": {
      "filter": "string",
      "next_page_token": "string",
      "page_size": "integer",
      "page_token": "string"
    }
  }
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Code Example

                  ## default
# 

# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# 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.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/cost/recommendations" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "scope": "ccm",
      "sort": [
        {
          "expression": "@potential_daily_savings",
          "order": "DESC"
        }
      ]
    },
    "id": "@resource_table:aws_ec2_instance",
    "type": "recommendations_filter"
  }
}
EOF

                
"""
Search cost recommendations returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.cloud_cost_management_api import CloudCostManagementApi
from datadog_api_client.v2.model.recommendations_filter_request import RecommendationsFilterRequest
from datadog_api_client.v2.model.recommendations_filter_request_data import RecommendationsFilterRequestData
from datadog_api_client.v2.model.recommendations_filter_request_data_attributes import (
    RecommendationsFilterRequestDataAttributes,
)
from datadog_api_client.v2.model.recommendations_filter_request_data_type import RecommendationsFilterRequestDataType
from datadog_api_client.v2.model.recommendations_filter_request_scope import RecommendationsFilterRequestScope
from datadog_api_client.v2.model.recommendations_filter_request_sort_items import RecommendationsFilterRequestSortItems

body = RecommendationsFilterRequest(
    data=RecommendationsFilterRequestData(
        attributes=RecommendationsFilterRequestDataAttributes(
            scope=RecommendationsFilterRequestScope.CCM,
            sort=[
                RecommendationsFilterRequestSortItems(
                    expression="@potential_daily_savings",
                    order="DESC",
                ),
            ],
        ),
        id="@resource_table:aws_ec2_instance",
        type=RecommendationsFilterRequestDataType.RECOMMENDATIONS_FILTER,
    ),
)

configuration = Configuration()
configuration.access_token = environ["DD_BEARER_TOKEN"]
configuration.unstable_operations["search_cost_recommendations"] = True
with ApiClient(configuration) as api_client:
    api_instance = CloudCostManagementApi(api_client)
    response = api_instance.search_cost_recommendations(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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" python3 "example.py"
# Search cost recommendations returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.access_token = ENV["DD_BEARER_TOKEN"]
  config.unstable_operations["v2.search_cost_recommendations".to_sym] = true
end
api_instance = DatadogAPIClient::V2::CloudCostManagementAPI.new

body = DatadogAPIClient::V2::RecommendationsFilterRequest.new({
  data: DatadogAPIClient::V2::RecommendationsFilterRequestData.new({
    attributes: DatadogAPIClient::V2::RecommendationsFilterRequestDataAttributes.new({
      scope: DatadogAPIClient::V2::RecommendationsFilterRequestScope::CCM,
      sort: [
        DatadogAPIClient::V2::RecommendationsFilterRequestSortItems.new({
          expression: "@potential_daily_savings",
          order: "DESC",
        }),
      ],
    }),
    id: "@resource_table:aws_ec2_instance",
    type: DatadogAPIClient::V2::RecommendationsFilterRequestDataType::RECOMMENDATIONS_FILTER,
  }),
})
p api_instance.search_cost_recommendations(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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" rb "example.rb"
// Search cost recommendations returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.CloudCostManagementApi;
import com.datadog.api.client.v2.model.CostRecommendationArray;
import com.datadog.api.client.v2.model.RecommendationsFilterRequest;
import com.datadog.api.client.v2.model.RecommendationsFilterRequestData;
import com.datadog.api.client.v2.model.RecommendationsFilterRequestDataAttributes;
import com.datadog.api.client.v2.model.RecommendationsFilterRequestDataType;
import com.datadog.api.client.v2.model.RecommendationsFilterRequestScope;
import com.datadog.api.client.v2.model.RecommendationsFilterRequestSortItems;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
    defaultClient.setUnstableOperationEnabled("v2.searchCostRecommendations", true);
    CloudCostManagementApi apiInstance = new CloudCostManagementApi(defaultClient);

    RecommendationsFilterRequest body =
        new RecommendationsFilterRequest()
            .data(
                new RecommendationsFilterRequestData()
                    .attributes(
                        new RecommendationsFilterRequestDataAttributes()
                            .scope(RecommendationsFilterRequestScope.CCM)
                            .sort(
                                Collections.singletonList(
                                    new RecommendationsFilterRequestSortItems()
                                        .expression("@potential_daily_savings")
                                        .order("DESC"))))
                    .id("@resource_table:aws_ec2_instance")
                    .type(RecommendationsFilterRequestDataType.RECOMMENDATIONS_FILTER));

    try {
      CostRecommendationArray result = apiInstance.searchCostRecommendations(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling CloudCostManagementApi#searchCostRecommendations");
      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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" java "Example.java"
// Search cost recommendations returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_cloud_cost_management::CloudCostManagementAPI;
use datadog_api_client::datadogV2::api_cloud_cost_management::SearchCostRecommendationsOptionalParams;
use datadog_api_client::datadogV2::model::RecommendationsFilterRequest;
use datadog_api_client::datadogV2::model::RecommendationsFilterRequestData;
use datadog_api_client::datadogV2::model::RecommendationsFilterRequestDataAttributes;
use datadog_api_client::datadogV2::model::RecommendationsFilterRequestDataType;
use datadog_api_client::datadogV2::model::RecommendationsFilterRequestScope;
use datadog_api_client::datadogV2::model::RecommendationsFilterRequestSortItems;

#[tokio::main]
async fn main() {
    let body = RecommendationsFilterRequest::new(
        RecommendationsFilterRequestData::new(
            RecommendationsFilterRequestDataType::RECOMMENDATIONS_FILTER,
        )
        .attributes(
            RecommendationsFilterRequestDataAttributes::new()
                .scope(RecommendationsFilterRequestScope::CCM)
                .sort(vec![RecommendationsFilterRequestSortItems::new()
                    .expression("@potential_daily_savings".to_string())
                    .order("DESC".to_string())]),
        )
        .id("@resource_table:aws_ec2_instance".to_string()),
    );
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.search_cost_recommendations", true);
    let api = CloudCostManagementAPI::with_config(configuration);
    let resp = api
        .search_cost_recommendations(body, SearchCostRecommendationsOptionalParams::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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Search cost recommendations returns "OK" response
 */

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

const configuration = client.createConfiguration({
  authMethods: {
    AuthZ: {
      accessToken: process.env.DD_BEARER_TOKEN as string,
    },
  },
});
configuration.unstableOperations["v2.searchCostRecommendations"] = true;
const apiInstance = new v2.CloudCostManagementApi(configuration);

const params: v2.CloudCostManagementApiSearchCostRecommendationsRequest = {
  body: {
    data: {
      attributes: {
        scope: "ccm",
        sort: [
          {
            expression: "potential_daily_savings.amount",
            order: "DESC",
          },
        ],
      },
      id: "@resource_table:aws_ec2_instance",
      type: "recommendations_filter",
    },
  },
};

apiInstance
  .searchCostRecommendations(params)
  .then((data: v2.CostRecommendationArray) => {
    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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" tsc "example.ts"
// Search cost recommendations 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.RecommendationsFilterRequest{
		Data: datadogV2.RecommendationsFilterRequestData{
			Attributes: &datadogV2.RecommendationsFilterRequestDataAttributes{
				Scope: datadogV2.RECOMMENDATIONSFILTERREQUESTSCOPE_CCM.Ptr(),
				Sort: []datadogV2.RecommendationsFilterRequestSortItems{
					{
						Expression: datadog.PtrString("@potential_daily_savings"),
						Order:      datadog.PtrString("DESC"),
					},
				},
			},
			Id:   datadog.PtrString("@resource_table:aws_ec2_instance"),
			Type: datadogV2.RECOMMENDATIONSFILTERREQUESTDATATYPE_RECOMMENDATIONS_FILTER,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN"))
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.SearchCostRecommendations", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewCloudCostManagementApi(apiClient)
	resp, r, err := api.SearchCostRecommendations(ctx, body, *datadogV2.NewSearchCostRecommendationsOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `CloudCostManagementApi.SearchCostRecommendations`:\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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" go run "main.go"