# Enrich an AWS cloud usage report using the API
Source: https://greenpixie.com/docs/guides/enrich-cur-api

How to join Greenpixie factors onto your own usage data.

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 usage data stays in your own environment. 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](/guides/getting-started-api)) and your exported usage data (see [Getting your cloud usage data](/guides/cloud-usage-data)).

## How enrichment works [#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 [#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. Build your next request from these values so nothing is hard-coded.

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

## Step 2. Pull the rate card [#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. Each page holds up to 1,000 records.

```bash
curl -G "https://api.greenpixie.com/v1/ratecards/cloud/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 [#step-3-join-onto-your-aws-cur]

Use the **rate code** and the **pricing unit** as the join columns. Spot rows carry a synthetic SKU, so the rate code is the reliable join column. The rate card's `pricing_unit` holds the same values as the CUR's `pricing_unit` column, for example `Hrs`, `GB-Mo` and `Requests`, so join the two columns directly, then multiply the usage amount by each factor to add your new columns.

```sql
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 b.pricing_unit      = 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.

## Data periods, refresh, and caching [#data-periods-refresh-and-caching]

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

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. To reproduce or audit past enrichment runs, store the rate card output alongside your results.

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](https://api.greenpixie.com/v1/docs) for the full parameter reference.

## Next steps [#next-steps]

- [Read the API documentation](https://api.greenpixie.com/v1/docs): The discover-then-query workflow, versioning, pagination, filtering and error codes.
- [Getting your cloud usage data](https://greenpixie.com/docs/guides/cloud-usage-data): Export the usage data you will enrich against the rate card.