Anomalies API

Cloud cost anomaly detection provides seamless end-to-end monitoring of spikes in your cloud billing across all your projects and services. See cost anomalies for more information.

The Anomalies API enables you to programmatically retrieve cloud cost or usage anomalies for Google Cloud, Amazon Web Services, and Microsoft Azure.

📘
Required Permissions
Cloud Analytics User

Anomalies API has the following methods:

anomalies.list

The anomalies.list method provides a list of all anomalies available for your cloud platforms.

You can filter the list by using one or more of the following parameters:

Parameter	Description
`minCreationTime`	`string` Min value for a time of an anomaly, in milliseconds since the POSIX epoch. If set, only anomalies happened after or at this timestamp are returned.
`maxCreationTime`	`string` Max value for a time of an anomaly time, in milliseconds since the POSIX epoch. If set, only anomalies happened before or at this timestamp are returned.
`filter`	`string` An expression for filtering the results of the request. The syntax is `key:[<value>]`. For example, the `platforms:google-cloud` will filter the list to only Google Cloud anomalies. Supported filter keys: `platform` - `google-cloud`, `amazon-web-services`, or `platform:microsoft-azure` Learn more about how to use filter *.list requests

Parameter

Description

minCreationTime

string
Min value for a time of an anomaly, in milliseconds since the POSIX epoch. If set, only anomalies happened after or at this timestamp are returned.

maxCreationTime

string
Max value for a time of an anomaly time, in milliseconds since the POSIX epoch. If set, only anomalies happened before or at this timestamp are returned.

filter

string
An expression for filtering the results of the request. The syntax is key:[<value>]. For example, the platforms:google-cloud will filter the list to only Google Cloud anomalies.

Supported filter keys:

platform - google-cloud, amazon-web-services, or platform:microsoft-azure Learn more about how to use filter *.list requests

Sample anomalies.list Request using both minCreationTime and filter parameters:

curl --location --request GET 'https://api.doit.com/anomalies/v1/?filter=serviceName:BigQuery&minCreationTime=1599436800000' \
--header 'Authorization: Bearer your-api-key'

📘
YOUR_API_KEY
Replace "YOUR_API_KEY" with your actual API key as explained at Get Started

Sample anomalies.list Response:

{
  "rowCount": 2,
  "anomalies": [
    {
      "id": "5c981868-e44a-4e57-93ad-8d5c1cff91fe",
      "billingAccount": "12345",
      "attribution": "",
      "costOfAnomaly": 446.41187273569216,
      "platform": "amazon-web-services",
      "scope": "123412341234",
      "serviceName": "Amazon Simple Notification Service",
      "top3SKUs": [
        {
          "name": "Requests-Tier1",
          "cost": 120
        },
        {
          "name": "USW2-Requests-Tier1",
          "cost": 50
        },
        {
          "name": "USW1-Requests-Tier1",
          "cost": 50
        },
        {
          "name": "Other",
          "cost": 700
        }
      ],
      "severityLevel": "warning",
      "timeFrame": "daily",
      "startTime": 1648508400000,
      "status": null,
      "endTime": null,
      "acknowledged": true
    },
    {
      "id": "ef017423-c4fa-4b04-abac-1bf8d09412dc",
      "billingAccount": "12345",
      "attribution": "",
      "costOfAnomaly": 431.72334855641634,
      "platform": "amazon-web-services",
      "scope": "123412341234",
      "serviceName": "AWS Key Management Service",
      "top3SKUs": [
        {
          "name": "us-west-2-KMS-Requests",
          "cost": 50
        },
        {
          "name": "us-west-1-KMS-Requests",
          "cost": 50
        },
        {
          "name": "us-east-2-KMS-Requests",
          "cost": 50
        },
        {
          "name": "Other",
          "cost": 700
        }
      ],
      "severityLevel": "warning",
      "timeFrame": "daily",
      "startTime": 1648501200000,
      "status": null,
      "endTime": null,
      "acknowledged": true
    }
  ]
}

anomalies.get

Get the full details of the individual anomaly using the anomaly id.

Sample anomalies.get Request

curl --location --request GET 'https://api.doit.com/anomalies/v1/e34ddb53-514f-4f75-ad1f-6d3089b3c572' \
--header 'Authorization: Bearer {YOUR_API_KEY}'

Sample anomalies.get Response:

{
  "anomalyChartUrl": "https://storage.googleapis.com/me-doit-intl-com-gcp-anomalies/e34ddb53-514f-4f75-ad1f-6d3089b3c572.png",
  "billingAccount": "xxxxxxxxxxxxxxxx",
  "attribution": "All AWS Resources",
  "costOfAnomaly": 83.49,
  "platform": "amazon-web-services",
  "scope": "123412341234",
  "serviceName": "Amazon Elastic Compute Cloud",
  "top3SKUs": [
    {
      "name": "EUC1-BoxUsage:c5.4xlarge",
      "cost": 83.49
    }
  ],
  "severityLevel": "critical",
  "timeFrame": "DAILY",
  "startTime": 1757030400000,
  "status": "inactive",
  "endTime": 1757408400000,
  "acknowledged": false,
  "resourceData": [
    {
      "cost": 14.744000434875488,
      "resource_id": "i-1234e70a5ca5cabcd",
      "sku_description": "EUC1-BoxUsage:c5.4xlarge",
      "operation": "RunInstances"
    },
    {
      "cost": 14.744000434875488,
      "resource_id": "i-1234709eabcd4282",
      "sku_description": "EUC1-BoxUsage:c5.4xlarge",
      "operation": "RunInstances"
    },
    {
      "cost": 9.96987596899271,
      "resource_id": "i-123489b3021abcd0d",
      "sku_description": "EUC1-BoxUsage:c5.4xlarge",
      "operation": "RunInstances"
    },
    {
      "cost": 9.652146607637405,
      "resource_id": "i-4567bfcde3abcdd06",
      "sku_description": "EUC1-BoxUsage:c5.4xlarge",
      "operation": "RunInstances"
    },
... ...
  ]
}

Response Body Fields

Field	Description
`billingAccount`	`string` Unique anomaly identifier
`platform`	`string` The cloud platform for the anomaly. Can be `google-cloud`, `amazon-web-services`, or `microsoft-azure`
`scope`	`string` The Google Cloud project ID, AWS account ID, or Azure resource group name for the given anomaly
`serviceName`	`string` The name of the service causing the anomaly. Examples are EC2, BigQuery, SQS, etc.
`severityLevel`	`string` All anomalies are classified as "info", "warning" or "critical"
`timeFrame`	`string` Anomalies can be DAILY (when a certain day is abnormally large compared to other days) or HOURLY (a certain hour is abnormally large compared to other hours of the same day).
`startTime`	`number` The time when this anomaly was detected, in milliseconds since the epoch.`
`acknowledged`	`boolean` Indicates whether the anomaly has been acknowledged.
`resourceData`	Array of `objects` Resources that contribute to the anomaly.