Anomaly Detection End Point

Summary

The Anomaly Detection API end point can be used to retrieve spending anomalies and create anomaly subscriptions as outlined in Anomaly Detection.

Table 1. API type
API type	Endpoint	Description
GET	/anomalies	used to get anomalies or a single anomaly using id param
POST	/subscriptions	used to create a subscription
GET	/subscriptions	used to get subscriptions
GET	/subscriptions/:subscriptionId	used to get a single subscription using subscriptionId
PUT	/subscriptions/:subscriptionId	used to update a subscription using subscriptionId
DELETE	/subscriptions/:subscriptionId	used to delete a subscription from our records

The Anomalies Object

date (string) - Date of the anomaly, e.g., "2018-02-14"

enhancedServiceName (string) - e.g., AWS EC2

usageFamily (string) - e.g., Data Transfer

unblendedCost (number) - Total cost for the day

unusualSpend (number) - The unusual portion of the spend for the day.

vendorAccountName (string) - Name associated with the account where the anomaly occurred

tags (array) - list of tag objects associated with the anomaly. Each object contains tag, tag Name and vendor Tag Value

businessDimensions (array) - list of businessDimension objects associated with the anomaly. Each object contains category, categoryKey and categoryValue

id (string) - the unique identifier used to look up a specific anomaly.

unusualSpendPercentage (string) - The unusual percentage of the spend for the day.

issueFields (array) - list of of Jira or ServiceNow issue objects associated with the anomaly.

GET Endpoint:

Example: https://api.cloudability.com/v3/anomalies

Query Parameters for date range lookup.

Table 2. Parameter
Parameter	Required	Description
startDate	Yes	the start date of the query
endDate	Yes	the end date of the query
viewId	Yes	the view being used for the request

Example request to retrieve a list of anomalies

curl --location 'https://api.cloudability.com/v3/anomalies?viewId=<viewId>&startDate=<year-month-day>&endDate=<year-month-day>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <envID>' \
--header 'Content-Type: application/json'

Example Response

{"result":[
{"date":"<date>","type":"<type>","enhancedServiceName":"<serviceName>","usageFamily":"<usageFamily>","unblendedCost":"<cost>",
"unusualSpend":"<unusualSpend>","vendorAccountName":"<account name>","currencyCode":"<currency code>","tags":["tag":"<tagId>", 
"tagName":"<tagName>"],"businessDimensions":["category":"<categoryID>", "categoryKey":"<categoryKey>"],"id":<id>,
"unusualSpendPercentage":"<percentage>","issueFields":[]},
{"date":"<date>","type":"<type>","enhancedServiceName":"<serviceName>","usageFamily":"<usageFamily>","unblendedCost":"<cost>",
"unusualSpend":"<unusualSpend>","vendorAccountName":"<account name>","currencyCode":"<currency code>","tags":["tag":"<tagId>", 
"tagName":"<tagName>"],"businessDimensions":["category":"<categoryID>", "categoryKey":"<categoryKey>"],"id":<id>,
"unusualSpendPercentage":"<percentage>","issueFields":[]},
{"date":"<date>","type":"<type>","enhancedServiceName":"<serviceName>","usageFamily":"<usageFamily>","unblendedCost":"<cost>",
"unusualSpend":"<unusualSpend>","vendorAccountName":"<account name>","currencyCode":"<currency code>","tags":["tag":"<tagId>", "tagName":"<tagName>"],"businessDimensions":["category":"<categoryID>", "categoryKey":"<categoryKey>"],"id":<id>,"unusualSpendPercentage":"<percentage>","issueFields":[]}
]}

Query Parameters for id lookup

Table 3. Query Parameters
Parameter	Required	Description
id	Yes	the anomaly's ID
viewId	Yes	The view being used in the request

Example request to retrieve a single anomaly.


curl --location 'https://api.cloudability.com/v3/anomalies?viewId=<viewId>&id=<anomalyId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <envID>' \
--header 'Content-Type: application/json'

Example Response


{"result":[{"date":"<date>","type":"<type>","enhancedServiceName":"<serviceName>","usageFamily":"<usageFamily>","unblendedCost":"<cost>","unusualSpend":"<unusualSpend>",
"vendorAccountName":"<account name>","currencyCode":"<currency code>","tags":["tag":"<tagId>", "tagName":"<tagName>"],"businessDimensions":["category":"<categoryID>",
 "categoryKey":"<categoryKey>"],"id":<id>,"unusualSpendPercentage":"<percentage>","issueFields":[]}]}

More information on filters:

The get anomalies request does handle filter requests, but it will only work if provided valid Dimension, Operator and Value parameters. It is recommended to use the filters on the frontend because the Dimension, Operator and Value parameters will auto-populate based on the environment.

Example request with filters

curl --location 'https://api.cloudability.com/v3/anomalies?viewId=<viewId>&startDate=<year-month-day>&endDate=<year-month-day>&filter=<dimension><operator><value>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <envID>' \
--header 'Content-Type: application/json'

The Subscriptions Object

SubscriptionId (string) - UUID for the subscription

viewId (string) - The view configured on the subscription

unusualSpendThreshold (int) - The unusual spend threshold configured for the subscription

unusualPercentageThreshold (int) - The unusual percentage threshold configured for the subscription

delivery (object) - The object contains the method of alerting

sharedUserIds (string) - (optional) The users that have been shared this subscription

description (string) - (optional) The set description for the subscription

anomalyIgnoreRecord (object) - (optional) The current ignore configuration set for this subscription

Example Subscriptions Object

POST endpoint:

Example: https://api.cloudability.com/v3/anomaly-subscriptions

Table 4. Query parameters
Parameter	Required	Description
viewId	Yes	the view being used for the request

Example request to create a new subscription

 curl -X POST --location 'https://api.cloudability.com/v3/anomaly-subscriptions?viewId=<viewId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <envID>' \
--header 'Content-Type: application/json' \
--data '{"unusualSpendThreshold":<amount>, "unusualPercentageThreshold":<amount>, "delivery": {"method":"<pagerduty or email>"}}'

Shared users and Description Example Request

 curl -X POST --location 'https://api.cloudability.com/v3/anomaly-subscriptions?viewId=<viewId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <envID>' \
--header 'Content-Type: application/json' \
--data '{"unusualSpendThreshold":<amount>,"description":"<description>","sharedUserIds":["<userId>", 
"<userId>"],"unusualPercentageThreshold":<amount>,"delivery":{"method":"<pagerduty or email>"}}'

Example Response:

{"result":{"subscriptionId":"<subId>","orgId":"<orgId>","viewId":"<viewId>","userId":"<userId>","unusualSpendThreshold":<spend amount>,
"unusualPercentageThreshold":<percentage amount>,"defaultCurrency":"<currency Code>","creatorId":"<userId>",
"createdAt":"<timeStamp>","updatedAt":"<timeStamp>","delivery":{"method":"<pagerduty or email>","recipient":"<userId>"}}}

Clarification on creating a subscription for only unusualSpendThreshold or unusualPercentageThreshold:

If the creator of the subscription wants only unusalSpendThreshold or unusualPercentageThreshold then only include which one is required in the request.

unusualSpendThreshold only request body example:
```
--data '{"unusualSpendThreshold":<amount>,"description":"<description>",
"sharedUserIds":["<userId>"],"delivery":{"method":"<pagerduty or email>"}}'
```
- setting unsualSpendThreshold or unusalPercentageThreshold to = 0 will set that threshold to 0 because there are some customers that do use that.

GET endpoint:

Example: https://api.cloudability.com/v3/anomaly-subscriptions

Table 5. Query parameters
Parameter	Required	Description
viewId	Yes	the view being used for the request

Example Request

curl --location 'https://api.cloudability.com/v3/anomaly-subscriptions?viewId=<viewId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <env id>' \
--header 'Content-Type: application/json'

Example Response (1 example with a sharedUserIds populated and 1 without sharedUserIds populated)

{"result":[
      {"subscriptionId":"<subscriptionId>","orgId":"<orgId>","viewId":"<viewId>","userId":"<userId>","unusualSpendThreshold":<unusualSpendThreshold>,
      "unusualPercentageThreshold":<unusualPercentageThreshold>,"defaultCurrency":"<currency Code>","creatorId":"<userId>","createdAt":"<timeStamp>",
      "updatedAt":"<timeStamp>","delivery":{"method":"<pagerduty or email>","recipient":"<userId>"},"sharedUserIds":"<userId>,<userId>"},
      {"subscriptionId":"<subscriptionId>","orgId":"<orgId>","viewId":"<viewId>","userId":"<userId>","unusualSpendThreshold":<unusualSpendThreshold>,
      "unusualPercentageThreshold":<unusualPercentageThreshold>,"defaultCurrency":"<currency Code>","creatorId":"<userId>","createdAt":"<timeStamp>",
       "updatedAt":"<timeStamp>","delivery":{"method":"<pagerduty or email>","recipient":"<userId>"}}
      ]}

GET endpoint: /v3/subscriptions/<subscriptionId>

Example: https://api.cloudability.com/v3/anomaly-subscriptions/<subscriptionId>

Example Request

curl --location 'https://api.cloudability.com/v3/anomaly-subscriptions/<subscriptionId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <env id>' \
--header 'Content-Type: application/json'

Example Response

{"result":
  {"subscriptionId":"<subscriptionId>","orgId":"<orgId>","viewId":"<viewId>","userId":"<userId>","unusualSpendThreshold":<unusualSpendThreshold>,"unusualPercentageThreshold":<unusualPercentageThreshold>,"defaultCurrency":"<currency Code>","creatorId":"<userId>","createdAt":"<timeStamp>","updatedAt":"<timeStamp>","delivery":{"method":"<pagerduty or email>","recipient":"<userId>"},"sharedUserIds":"<userId>,<userId>"}
}

PUT endpoint:

Example: https://api.cloudability.com/v3/anomaly-subscriptions/<subscriptionId>?viewId=<viewId>

Table 6. Query parameters
Parameter	Required	Description
viewId	Yes	the view being used for the request

Example Request

curl -X PUT --location 'https://api.cloudability.com/v3/anomaly-subscriptions/<subscriptionId>?viewId=<viewId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <env id>' \
--header 'Content-Type: application/json' \
--data '{"subscriptionId":"<subscriptionId>","orgId":"<orgId>","userId":"<userId>","unusualSpendThreshold":<unusualSpendThreshold>,
"unusualPercentageThreshold":<unusualPercentageThreshold>,"defaultCurrency":"<currency Code>","creatorId":"<userId>","createdAt":"<timeStamp>",
"updatedAt":"<timeStamp>","delivery":{"method":"<pagerduty or email>","recipient":"<userId>"},"sharedUserIds":["<userId>,<userId>"],"source":"<source method>","description":""}'

Shared users clarification:

subscription owner can add users to the array [] of sharedUserIDs in the request. userIds must be comma seperated.

Example Response

200, only will response with an error if there was one

DELETE endpoint:

Example: https://api.cloudability.com/v3/anomaly-subscriptions/<subscriptionId>

Example Request

curl -X DELETE --location 'https://api.cloudability.com/v3/anomaly-subscriptions/<subscriptionId>' \
--header 'apptio-opentoken: <token>' \
--header 'apptio-environmentid: <env id>' \
--header 'Content-Type: application/json'

Example Response

200, only will response with an error if there was one.