Cloudability API

Cloudability API Documentation

Welcome to the Cloudability API documentation.

At Cloudability our public API is a first class citizen. As much as we know you love using our console, a well factored API can deliver and enable myriad use cases beyond even our imagination.
If you are a large public cloud user you'll find intelligent ways to automate scripting of repetitive tasks that would be impractical to manage manually at the scale you require. We also expect to see more machine to machine integrations where information is be shared between systems, augmenting important data sets and supporting the delivery of information to end users in a medium that works for them.

Get Started

Reservation Portfolio Endpoint

Summary

The RI Portfolio endpoint can be used to retrieve a detailed list of all Reserved Instances (RIs) as well as understand how well utilized these reservations were over a particular period of time. For more information on the RI Portfolio please see our knowledge base article.

Included examples in this document will focus on compute reservations an commitments but the patterns for other supported AWS services (i.e. RDS, Redshift and ElastiCache) are consistent with EC2 examples.

Endpoint Particulars

The endpoints are read-only for retrieving a list of Reservation Objects
AWS EC2 RI endpoint: /reservations/aws/savings/ec2
AWS Savings Plan endpoint: /reservations/aws/portfolio/savingsPlan
Azure compute RI endpoint : /reservations/azure/portfolio/compute
GCP compute CUD endpoint: /reservations/gcp/portfolio/ce
AWS RDS RI endpoint: /reservations/aws/savings/rds
AWS Redshift RI endpoint: /reservations/aws/savings/redshift
AWS ElastiCache endpoint: /reservations/aws/savings/elasticache

AWS RI Arguments

Argument

Required?

Description

Type

start

yes

Beginning of time window to look for RI usage, e.g. "2018-01-01"

string

end

yes

End of time window to look for RI usage e.g. "2018-01-01"

string

basis

no

Defaults to 'cash' though you may pass 'adjusted' to see savings net of any custom pricing rules

string

viewId

no

Defaults to 0. Only account-group based views are supported

integer

The AWS Reservation Object

availabilityZone (string): If applicable
count (integer): Number of reserved instances in the RI
duration (integer): duration of the RI in seconds
end (string): The timestamp when the RI ends e.g., '2018-07-06T18:00:00Z'
instanceType (string): e.g., 'r3.large'
multiAz (string): Single-AZ or Multi-AZ (RDS only)
netSavings (number): Total savings, reflecting the difference between what you paid for an RI and how much the hours you actually consumed would have cost if purchased On-Demand
offeringClass (string): 'standard' or 'convertible
offeringType (string): 'NoUpfront', 'PartialUpfront' or 'AllUpfront'
operatingSystem (string): Software and associated licensing info. e.g., "Linux" or "Windows with SQL Server Standard
overallUtilization (number): The percent of purchased hours that were applied to a running instance
region (string): e.g., 'us-east-1',
reservationIdentifier (string): The vendor supplied unique id for your reservation
scope (string): 'Region' or 'Availability Zone'
start (string): The timestamp when the RI begins e.g., '2018-07-06T18:00:00Z'
state (string): 'retired' or 'active'
tenancy (string): 'default' or 'dedicated'
term (integer): duration of the RI in years
units (integer): number of ISF-Normalized hours in the RI
unrealizedSavings (number): Any additional savings you could have achieved assuming complete RI utilization
vendorAccountId (string): 12 digit string corresponding to your AWS account ID

Example AWS Reservation Object

{
  "result": [
    {
      "availabilityZone": "",
      "count": 1,
      "duration": 10368000,
      "end": "2018-11-03T16:17:39Z",
      "instanceType": "t2.large",
      "multiAz": "(not set)",
      "netSavings": 25.416000000000015,
      "offeringClass": "standard",
      "offeringType": "NoUpfront",
      "operatingSystem": "Linux",
      "overallUtilization": 1,
      "region": "us-east-1",
      "reservationIdentifier": "0202a336-1712-1712-1712-0202a336",
      "scope": "Region",
      "start": "2018-07-06T18:00:00Z",
      "state": "active",
      "tenancy": "default",
      "term": 1,
      "units": 4,
      "unrealizedSavings": 0,
      "vendorAccountId": "0123456789"
    }
  ]
}

Example AWS Reservation Portfolio Requests

List Subscriptions

The following will list any EC2 reservations that were active between March 1 and March 15, 2018 and with no view restrictions.

curl "https://api.cloudability.com/v3/reservations/aws/savings/ec2?basis=cash&start=2018-08-01&end=2018-08-15&viewId=0" \ 
     -u '[auth_token]:'

AWS Savings Plan Arguments

Argument

Required

Description

Type

filter

No

Attributes Measure(field) and value that savings plans in response must have. E.g. ‘InstanceFamily’ ‘r5’

string

limit

No

Part of pagination range request for maximum count per page.

integer

offset

No

Part of pagination range request designating the first asset to be returned in the response.

integer

sortOrder

No

Measure(field) and direction (ascending/descending) order of assets in response.

string

viewId

No

Cloudability ViewID to be respected in response.

integer

The AWS Savings Plan Object

vendorAccountId (string): 12 digit string corresponding to your AWS account ID
savingsPlanId (string): the vendor assigned identifier for the Savings Plan
savingsPlanArn (string): The vendor assigned Savings Plan unique global identifier
duration (integer): duration of the savings plan in seconds
start (integer): The Epoch millisecond formatted time stamp of the Savings Plan becoming active
end (integer): The Epoch millisecond formatted time stamp of when the Savings Plan will terminate
term (integer): Savings Plan Term length in years
type (string): Savings Plan type (EC2 or Compute)
state (string): Current state of the Savings plan (e.g. Active)
region (string): EC2 Savings Plan region designation (not applicable for Compute plans)
ec2InstanceFamil (string): EC2 Savings Plan applicable instance family designation (not applicable for Compute plans)
offeringType (string): Payment method/model designation (e.g. No Upfront)
hourlyCommitment (integer): Hourly Savings Plan monetary commitment
totalCommitment (integer): Total monetary commitment over the life of the savings plan
currencyCode (string): Monetary units for Savings Plan hourly and total commitment
upfront (integer): Initial payment made at inception of Savings Plan
frequency (string): Applicable pricing interval units
amount (integer): Applicable pricing per frequency unit specified

Example AWS Savings Plan Object

{
  "result": [
    {
      "vendorAccountId": "############",
      "accountName": "AWS Consolidated Master",
      "savingsPlanId": "xx###x##x-xxxx-#xxx-xx##-x####x###xxx",
      "savingsPlanArn": "arn:aws:savingsplans::############:savingsplan/xx###x##x-xxxx-#xxx-xx##-x####x###xxx",
      "description": "1 year No Upfront r5 EC2 Instance Savings Plan in us-east-1",
      "start": 1573079358000,
      "end": 1604615357000,
      "duration": 31536000,
      "term": 1,
      "type": "EC2Instance",
      "state": "active",
      "region": "us-east-1",
      "ec2InstanceFamily": "r5",
      "offeringType": "No Upfront",
      "hourlyCommitment": 1,
      "totalCommitment": 8760,
      "pricing": {
        "offeringId": "c#####xx#-xxx#-##xx-x##x-#xx####xx#x#",
        "currencyCode": "USD",
        "upfront": 0,
        "recurring": {
          "frequency": "Hourly",
          "amount": 1
        }
      },
      "tags": []
    },
    {
      "vendorAccountId": "############",
      "accountName": "AWS Consolidated Master",
      "savingsPlanId": "xx###x##x-xxxx-#xxx-xx##-x####x###xxx",
      "savingsPlanArn": "arn:aws:savingsplans::############:savingsplan/xx###x##x-xxxx-#xxx-xx##-x####x###xxx",
      "description": "1 year No Upfront Compute Savings Plan",
      "start": 1573145364000,
      "end": 1604681363000,
      "duration": 31536000,
      "term": 1,
      "type": "Compute",
      "state": "active",
      "region": "(not set)",
      "ec2InstanceFamily": "(not set)",
      "offeringType": "No Upfront",
      "hourlyCommitment": 1,
      "totalCommitment": 8760,
      "pricing": {
        "offeringId": "c#####xx#-xxx#-##xx-x##x-#xx####xx#x#",
        "currencyCode": "USD",
        "upfront": 0,
        "recurring": {
          "frequency": "Hourly",
          "amount": 1
        }
      },
      "tags": []
    }
  ],
  "meta": {
    "aggregate": {
      "quantity": 2,
      "hourlyCommitment": 2
    },
    "pagination": {
      "totalCount": 2
    }
  }
}

Example Savings Plan Inventory Request

List Savings Plans

The following will list the first 50 active or expired r5 EC2 Savings Plans in us-east-1 sorted by expiration date from those expiring soonest to those expiring farthest in the future.

curl "https://api.cloudability.com/v3/reservations/aws/portfolio/savingsPlan?filter&limit=50&offset=0&product=savingsPlan&sortOrder=%2Bend&viewId=0" \ 
     -u '[auth_token]:'

The Google Cloud Platform(GCP) Committed Use Discount(CUD) Object

reservationId(string): The vendor supplied unique id for your reservation
acountName(string): User assigned account ID
memory(integer): MB of memory allocated (at 1024MB/GB)
vcpus(integer): vCPUs allocated to the CUD
name(string): User assigned CUD name
term(integer): CUD term length in years
region(string): text description of the CUD's assigned region e.g. 'us-central'
status(string): current CUD status
statusMessage(string): long form status disctiption and explanation
creation(string): The Epoch millisecond formatted time stamp of when the CUD was requested
start(number): The Epoch millisecond formatted time stamp of when the CUD began applying to usage
end(number): The Epoch millisecond formatted CUD expiration time stamp
duration(integer): duration of the RI in seconds

Example GCP Reservation Object

{
  "result": [
    {
      "vendorAccountId": "prod-processing",
      "reservationId": "7648261############",
      "accountName": "prod-processing",
      "memory": 3840,
      "vcpus": 1,
      "description": "",
      "name": "commitment-1",
      "term": 1,
      "region": "us-central1",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/aws-processing/regions/us-central1/commitments/commitment-1",
      "status": "EXPIRED",
      "statusMessage": "The commitment is expired. It will not apply to current resource usage.",
      "creation": 1521072761000,
      "start": 1521097200000,
      "end": 1552633200000,
      "duration": 31536000
    },
    {
      "vendorAccountId": "production-reco",
      "reservationId": "79798##############",
      "accountName": "production-reco",
      "memory": 1024,
      "vcpus": 1,
      "description": "",
      "name": "production-reco-commitment-1",
      "term": 1,
      "region": "us-east1",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/cloudability-reco/regions/us-east1/commitments/production-reco-commitment-1",
      "status": "ACTIVE",
      "statusMessage": "The commitment is active, and so will apply to current resource usage.",
      "creation": 1547486436000,
      "start": 1547539200000,
      "end": 1579075200000,
      "duration": 31536000
    }
  ],
  "meta": {
    "aggregate": {
      "quantity": 2,
      "memory": 4864,
      "vcpus": 2
    },
    "pagination": {
      "totalCount": 2
    }
  }
}

Example GCP Reservation Portfolio Request

The following will generate a list of GCP CUDs

curl "https://api.cloudability.com/v3/reservations/gcp/portfolio/ce" \
     -u '[auth_token]:'

The Azur Reserved Instance Object

vendorAccountId(string):Vendor assigned unique alphanumeric subscription identifier
reservationId(string):Vendor assigned unique alphanumeric reservation identifier
AccountName(string):User assigned subscription name
size(string):On demand instance family covered by the reservation(e.g.'DS1_v2')
tier(string):On demand instance tier covered by the reservation (e.g.'Standard')
term(integer):Reservation term length in years
quantity(integer):Number of instances covered by the reservation
region(string):Text description of the reservation's assigned region e.g. 'westus2'
state(string):Current reservation status
start(number):The Epoch millisecond formatted time stamp of when the CUD began applying to usage
end(number):The Epoch millisecond formatted CUD expiration time stamp
currencyCode(string):The currency reporting type for the reservation
upfront**(integer):The up front reservation purchase price in the applicable currency

Example Azure Reservation Object

{
  "result": [
    {
      "vendorAccountId": "2####252-2##4-4##e-9##7-b95#########",
      "reservationId": "45####04-3X#2-4##7-b##6-35c##XX###X#",
      "accountName": "AZU Staging US",
      "size": "DS1_v2",
      "tier": "Standard",
      "term": 1,
      "quantity": 3,
      "region": "westus2",
      "state": "Cancelled",
      "start": 1560211200000,
      "end": 1560729600000,
      "pricing": {
        "currencyCode": "USD",
        "upfront": 810
      }
    },
    {
      "vendorAccountId": "c####d37-eecc-##d6-###b-######da36a6",
      "reservationId": "XX6d##d7-b034-4XX8-a8a0-3bcc###a####",
      "accountName": "Azure Prod",
      "size": "B1s",
      "tier": "Standard",
      "term": 1,
      "quantity": 1,
      "region": "westus2",
      "state": "Succeeded",
      "start": 1557446400000,
      "end": 1588896000000,
      "pricing": {
        "currencyCode": "USD",
        "upfront": 53
      }
    },
    {
      "vendorAccountId": "26e#####-2##4-434e-####-b95f#####fd#",
      "reservationId": "3d####f7-0X##-40b0-b###-82bd######a#",
      "accountName": "AZU Staging US",
      "size": "DS1_v2",
      "tier": "Standard",
      "term": 1,
      "quantity": 2,
      "region": "westus2",
      "state": "Succeeded",
      "start": 1560729600000,
      "end": 1591747200000,
      "pricing": {
        "currencyCode": "USD",
        "upfront": 540
      }
    },
  "meta": {
    "aggregate": {
      "quantity": 6
    },
    "pagination": {
      "totalCount": 3
    }
  }
}

Example Azure Reservation Portfolio Request

The following will generate a list of Azure Reserved Instances

curl "https://api.cloudability.com/v3/reservations/azure/portfolio/compute" \
     -u '[auth_token]:'

Updated 8 months ago

Reservation Portfolio Endpoint


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.