Overview and usage

The Cloud Pricing API is a GraphQL-based API that includes all public prices from AWS, Azure and Google; it contains over 3 million prices! The prices are automatically updated via a weekly job. This API is used by the Infracost CLI, thus you do not need to interact with it directly, however, you can also use it independently.

GraphQL is a natural fit for cloud pricing as it can model the JSON structure used by cloud vendors. This enables you to query nested JSON structures using vendor-specific parameters, and request only the attributes you need to be returned in the response. For example, you can find all prices that match AWS EC2 m3.large instance in us-east-1 (over 400 prices), then explore the 30+ attributes that AWS return to describe instances (e.g. clockSpeed or networkPerformance).

Concepts#

The API has two main types: Products and Prices. Each product can have many Prices. This simple high-level schema provides flexibility to model the exact values that the cloud vendor APIs return at the same time as having useful top-level product filters. The values returned by the API are the same ones that the cloud vendors return in their APIs.

The main properties of Products are:

NameAWS examplesMicrosoft Azure examplesGoogle Cloud Platform examples
vendorNameawsazuregcp
serviceAmazonEC2, AWSLambda, awskmsVirtual Machines, Functions, Azure DNSCompute Engine, Cloud Functions, Cloud DNS
productFamilyDedicated Host, Provisioned Throughput, Elastic GraphicsCompute, Storage, DatabasesCompute Instance, License, Network
regionus-east-1, cn-north-1, us-gov-east-1eastus, uknorth, US Govus-east1, europe, australia-southeast1
attributes (array of key-value pairs)usagetype: UGE1-Lambda-Edge-Request, clockSpeed: 2.5 GHzproductName: Premium Functions, meterName: vCPU DurationmachineType: n2-highmem-64, description: Static Ip Charge

The main properties of Prices are:

NameDescriptionExample
USDPrice from the cloud vendor in the preferred ISO 4217 currency code (e.g. EUR, BRL or INR). For non-USD currencies, prices are converted from USD to the preferred currency at query time.USD: 0.2810000000
unitUnit for the priceunit: Hrs
descriptionAny additional descriptiondescription: Upfront Fee
startUsageAmountStart usage amount for price tier, only applicable for tiered pricingstartUsageAmount: 0
endUsageAmountEnd usage amount for price tier, only applicable for tiered pricingendUsageAmount: 10000
purchaseOptionPurchase option varies between vendorson_demand, reserved, spot, Consumption, preemptible
termPurchaseOptionTerm of the purchase optiontermPurchaseOption: All Upfront
termLengthLength of the purchase optiontermLength: 1yr
termOfferingClassOffering class or type of the termtermOfferingClass: standard

Usage#

Infracost runs a hosted version of this API that you can use:

  1. Register for an API key by downloading infracost and running infracost register.
  2. Pass the above API key using the X-Api-Key: xxxx HTTP header when calling https://pricing.api.infracost.io/graphql. The following example fetches the latest price for an AWS EC2 m3.large instance in us-east-1. More examples can be found here.
curl https://pricing.api.infracost.io/graphql \
-X POST \
-H 'X-Api-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
--data '
{"query": "{ products(filter: {vendorName: \"aws\", service: \"AmazonEC2\", region: \"us-east-1\", attributeFilters: [{key: \"instanceType\", value: \"m3.large\"}, {key: \"operatingSystem\", value: \"Linux\"}, {key: \"tenancy\", value: \"Shared\"}, {key: \"capacitystatus\", value: \"Used\"}, {key: \"preInstalledSw\", value: \"NA\"}]}) { prices(filter: {purchaseOption: \"on_demand\"}) { USD } } } "}
'

What will you build?#

Whilst our main use-case for developing the Cloud Pricing API is the Infracost CLI, we're excited to see what the community does with this API. Please share your use-cases and issues with us on GitHub or Slack or email.