Enrich an AWS cloud usage report using the API

The Greenpixie API lets you enrich your own cloud usage report in your own environment. You pull the rate card, join it onto your usage data, and multiply, so your data never leaves your control. This is the same enrichment Greenpixie's managed service performs, done on your side.

Before you start, you need an API key (see Getting started with the Greenpixie API) and your exported usage data (see Getting your cloud usage data).

How enrichment works

Pull the rate card at rate-code granularity, where each row is a single rate code with its exact per-unit factors. Join those rows onto your usage report on the rate code, then multiply each factor by the usage quantity on the line to get energy, carbon and water for it.

Step 1. Discover what you can read

Call GET /v1/ratecards first. It returns the (provider, granularity) combinations your key can read, the columns each one returns, the grid granularities and date ranges available, and every published version. Use these values to build your next request rather than hard-coding them.

curl "https://api.greenpixie.com/v1/ratecards" \
  -H "Authorization: Bearer $GPX_KEY"

Step 2. Pull the rate card

For a rate-code join, use the full granularity, which returns one row per rate code with exact per-rate factors. Filter to narrow the pull, and page through results with the cursor in links.next until it is null (up to 1,000 records per page).

curl -G "https://api.greenpixie.com/v1/ratecards/methodology/aws/full" \
  --data-urlencode "limit=1000" \
  --data-urlencode "region=us-east-1" \
  --data-urlencode "line_item_product_code=AmazonEC2" \
  -H "Authorization: Bearer $GPX_KEY"

Each row carries a rate_code, a pricing_unit, and the exact per-unit factors usage_electricity_consumption_kwh_per_pricing_unit, total_tonnes_co2e_per_pricing_unit, and total_water_litres_per_pricing_unit.

Step 3. Join onto your AWS CUR

Join on the rate code, not the SKU. Spot rows use a synthetic SKU, so the rate code is the reliable key. Normalise the pricing unit on both sides so units line up, then multiply the usage amount by each factor to add your new columns.

SELECT
    b.*,
    b.line_item_usage_amount * a.usage_electricity_consumption_kwh_per_pricing_unit AS usage_electricity_consumption_kwh,
    b.line_item_usage_amount * a.total_tonnes_co2e_per_pricing_unit                 AS total_tonnes_co2e,
    b.line_item_usage_amount * a.total_water_litres_per_pricing_unit                AS total_water_litres
FROM aws_cur b
LEFT JOIN api_output a
       ON b.pricing_rate_code = a.rate_code
      AND (
            CASE
                WHEN b.pricing_unit IN ('Hrs','Hour','Hours') THEN 'Hours'
                WHEN b.pricing_unit IN ('GB-Mo','GB-Month')    THEN 'GB-Month'
                ELSE b.pricing_unit
            END
          ) = a.pricing_unit;

Here aws_cur is your usage report and api_output is the rate card you pulled in step 2. The result is your CUR with energy, carbon and water added alongside cost, at the same granularity.

In this example the rate card and the usage cover the same month. If you are joining multiple months of usage to multiple months of rate cards, add the period to the join condition so each month of usage matches the rate card for that same month, applying the right carbon data to the right date.

Data periods, refresh, and caching

By default, the API enriches using the carbon intensity from the previous full calendar month. This refreshes two days into each new month, once the complete carbon data for the previous month is available.

This has an important consequence for historic data. If you do not cache and save the API output before the monthly refresh, you will not be able to retrieve that month's rate card again later without a licence that includes the historic data add-on. If you need to reproduce or audit past enrichment runs, store the rate card output alongside your results.

It also gives you a natural two-pass workflow. Enrich the current month's usage with the previous month's rate card as the month progresses, then re-enrich once the rate card refreshes on the 3rd of the following month, using that month's completed carbon data.

To pin a run to a specific dataset, set the version, grid_version and grid_period parameters. See the API documentation for the full parameter reference.

Next steps