List cost anomalies

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

GET https://api.ap1.datadoghq.com/api/v2/cost/anomalieshttps://api.ap2.datadoghq.com/api/v2/cost/anomalieshttps://api.datadoghq.eu/api/v2/cost/anomalieshttps://api.ddog-gov.com/api/v2/cost/anomalieshttps://api.us2.ddog-gov.com/api/v2/cost/anomalieshttps://api.datadoghq.com/api/v2/cost/anomalieshttps://api.us3.datadoghq.com/api/v2/cost/anomalieshttps://api.us5.datadoghq.com/api/v2/cost/anomalies

Overview

List detected Cloud Cost Management anomalies for the organization.

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

Arguments

Query Strings

Name

Type

Description

start

integer

Start time as Unix milliseconds. Defaults to the start of the latest stable seven-day window.

end

integer

End time as Unix milliseconds. Defaults to the end of the latest stable seven-day window.

filter

string

Optional JSON object mapping cost tag keys to allowed values, for example {"team":["payments"],"env":["prod"]}. Filters match anomaly dimensions or correlated tags.

min_anomalous_threshold

string

Minimum absolute anomalous cost change to include. Numeric value; defaults to 1.

min_cost_threshold

string

Minimum absolute actual cost to include. Numeric value; defaults to 0.

dismissal_cause

string

Filter by resolution state. Use none for unresolved anomalies, all or * for resolved anomalies, or a comma-separated list of causes.

order_by

string

Sort field. One of start_date, end_date, duration, max_cost, anomalous_cost, or dismissal_date. Defaults to anomalous_cost.

order

string

Sort direction. One of asc or desc. Defaults to desc.

limit

integer

Maximum number of anomalies to return. Defaults to 200.

offset

integer

Pagination offset. Defaults to 0.

provider_ids

array

Optional repeated cloud or SaaS provider filters, such as aws, gcp, azure, Oracle, datadog, OpenAI, or Anthropic.

Response

OK

Response object containing a list of detected Cloud Cost Management anomalies and aggregated totals.

Expand All

Field

Type

Description

data

object

Resource wrapper for the list of cost anomalies and aggregated totals.

attributes [required]

object

Cost anomaly results and aggregated totals for the queried window.

anomalies [required]

[object]

The list of cost anomalies that match the request.

actual_cost [required]

double

Actual cost incurred during the anomaly window.

anomalous_cost_change [required]

double

Anomalous cost change relative to the expected baseline.

anomaly_end [required]

int64

Anomaly end timestamp in Unix milliseconds.

anomaly_start [required]

int64

Anomaly start timestamp in Unix milliseconds.

correlated_tags [required]

object

Map of correlated tag keys to the list of correlated tag values.

<any-key>

[string]

The list of correlated values for the tag key.

dimensions [required]

object

Map of cost dimension keys to their values for the anomaly grouping.

<any-key>

string

The dimension value.

dismissal

object

Resolution metadata for an anomaly that has been dismissed.

cause [required]

string

Reason the anomaly was dismissed.

dismissal_id [required]

string

Unique identifier of the dismissal record.

message [required]

string

Optional message explaining the dismissal.

updated_at [required]

int64

Timestamp of the last dismissal update in Unix milliseconds.

updated_by [required]

string

Identifier of the user that last updated the dismissal.

max_cost [required]

double

Maximum cost observed during the anomaly window.

provider [required]

string

Cloud or SaaS provider associated with the anomaly (for example aws, gcp, azure).

query [required]

string

The metrics query that detected the anomaly.

uuid [required]

string

The unique identifier of the anomaly.

avg_daily_anomalous_cost [required]

double

Average daily anomalous cost change across the queried window.

total_actual_cost [required]

double

Total actual cost spent across the queried window for the matching providers.

total_anomalous_cost [required]

double

Sum of the anomalous cost change across all returned anomalies.

total_count [required]

int64

Total number of anomalies that match the request.

id [required]

string

Static identifier of the cost anomalies collection resource.

type [required]

enum

Type of the cost anomalies collection resource. Must be anomalies. Allowed enum values: anomalies

default: anomalies

{
  "data": {
    "attributes": {
      "anomalies": [
        {
          "actual_cost": 3001.24,
          "anomalous_cost_change": 1250.75,
          "anomaly_end": 1730429150000,
          "anomaly_start": 1730259950000,
          "correlated_tags": {
            "<any-key>": []
          },
          "dimensions": {
            "<any-key>": "string"
          },
          "dismissal": {
            "cause": "false_positive",
            "dismissal_id": "12345678-1234-1234-1234-123456789abc",
            "message": "This was expected due to planned infrastructure changes.",
            "updated_at": 1730344150000,
            "updated_by": "user@example.com"
          },
          "max_cost": 5000.5,
          "provider": "aws",
          "query": "sum:aws.cost.net.amortized{aws_cost_type IN (Usage,DiscountedUsage,SavingsPlanCoveredUsage) AND aws_product NOT IN (supportenterprise) AND service:\"ec2\"}.rollup(sum, daily)",
          "uuid": "b0a6aaa9-3c4c-48cb-9447-a0d1338b3e09"
        }
      ],
      "avg_daily_anomalous_cost": 625.375,
      "total_actual_cost": 3001.24,
      "total_anomalous_cost": 1250.75,
      "total_count": 1
    },
    "id": "anomalies",
    "type": "anomalies"
  }
}

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

                  # 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/cost/anomalies" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List cost anomalies returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.cloud_cost_management_api import CloudCostManagementApi

configuration = Configuration()
configuration.unstable_operations["list_cost_anomalies"] = True
with ApiClient(configuration) as api_client:
    api_instance = CloudCostManagementApi(api_client)
    response = api_instance.list_cost_anomalies()

    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"
# List cost anomalies returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_cost_anomalies".to_sym] = true
end
api_instance = DatadogAPIClient::V2::CloudCostManagementAPI.new
p api_instance.list_cost_anomalies()

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"
// List cost anomalies 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()
	configuration.SetUnstableOperationEnabled("v2.ListCostAnomalies", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewCloudCostManagementApi(apiClient)
	resp, r, err := api.ListCostAnomalies(ctx, *datadogV2.NewListCostAnomaliesOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `CloudCostManagementApi.ListCostAnomalies`:\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"
// List cost anomalies 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.CostAnomaliesResponse;

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

    try {
      CostAnomaliesResponse result = apiInstance.listCostAnomalies();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling CloudCostManagementApi#listCostAnomalies");
      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"
// List cost anomalies 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::ListCostAnomaliesOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListCostAnomalies", true);
    let api = CloudCostManagementAPI::with_config(configuration);
    let resp = api
        .list_cost_anomalies(ListCostAnomaliesOptionalParams::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
/**
 * List cost anomalies returns "OK" response
 */

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

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.listCostAnomalies"] = true;
const apiInstance = new v2.CloudCostManagementApi(configuration);

apiInstance
  .listCostAnomalies()
  .then((data: v2.CostAnomaliesResponse) => {
    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"