Getting started with the Greenpixie API
Make a key, explore the data, and run your first call.
The Greenpixie API serves a rate card of per-unit sustainability factors, energy (kWh), carbon (CO2e) and water (litres), for AWS, Azure and GCP. You join these factors onto your own cloud usage data to enrich it, without sending Greenpixie your billing data.
This guide is a practical walkthrough. Generate a key, explore the data in the browser, and run your first call. For the full endpoint reference, authentication details and versioning parameters, see the API documentation.
Sign in and choose your organisation
Go to app.greenpixie.com and sign in.
Your account belongs to an organisation, which is how Greenpixie groups your team, API key and entitlements. Use the organisation switcher in the bottom-left to switch between organisations or create a new one. Everything below runs against the organisation you have selected.
Generate your API key
In the left navigation, open Get your API key. Your key is generated for you automatically.
- Choose Reveal to show the key, then copy it.
- Choose Regenerate to rotate the key if it is ever exposed. The old key stops working straight away.
Treat the key like a password. You send it as a bearer token on every request, and in the examples below $GPX_KEY stands in for it.
Take the tour
Open the Cloud Data Explorer, then choose Tour at the top. The tour is a six-step walkthrough of the query builder. It covers how the detail level, region and service filters shape your results, and how the code panel at the bottom gives you the exact request to run yourself. It takes under a minute and is the fastest way to orient.
Build a query with the filters
The Cloud Data Explorer is a query builder over the same rate card the API serves. Configure a request in the sidebar and it writes the matching API call for you in real time.
- Provider, pick AWS, Azure or GCP.
- Detail level, how rows are grouped. Choose one row per Service, per Usage type, or per SKU / rate code. Service averages factors across all SKUs, and more detail means more rows.
- Region, narrow to specific regions. Factors vary by region because each draws on a different electricity grid mix. Leave empty to return every region.
- Service, pick the services you want factors for, for example
AmazonEC2. This maps to the provider's own service or product code. - More filters, filter on any other column in the rate card, such as pricing term or rate code. Choosing a more specific column switches the detail level to the most granular view.
- Advanced options, pin the methodology Version and the Grid period, and set the row Limit. The Grid period is the electricity grid mix period behind the factors, to Year, Month or Day precision. All three default to the latest data.
The Compute rate card data and the Cloud Data Explorer itself are available on the free tier across AWS, Azure and GCP, so you can build and run queries before writing any code. The AI and Grid rate cards are available to Greenpixie customers only.
Run it and read the results
Choose Run query. Results appear on the right, switchable between Table and JSON. The header above the results tells you how many rows matched and which dataset produced them, for example 100 of 5,384 rows · meth-v5.2.0 · grid 2025. Here meth-v5.2.0 is the methodology version and grid 2025 the grid period, so any result is reproducible.
You can download the table as a CSV, up to an export limit of 25,000 unique records.
Each row carries the product, region, pricing unit, and the energy, carbon and water factors per pricing unit.
Make the same call from your own environment
The code panel at the bottom of the sidebar holds the exact request behind your results, in cURL or Python, and updates live as you change the filters. Copy it and run it as-is.
The API returns up to 1,000 records per page. For larger pulls, page through the results using the cursor in links.next until it comes back null. See the API documentation for the full pagination walk.
curl -G "https://api.greenpixie.com/v1/ratecards/methodology/aws/usage" \
--data-urlencode "include_totals=true" \
--data-urlencode "limit=100" \
--data-urlencode "region=us-east-1" \
--data-urlencode "line_item_product_code=AmazonEC2" \
-H "Authorization: Bearer $GPX_KEY"The response returns a set of columns and one record per row.
{
"columns": [
"version",
"line_item_product_code",
"line_item_usage_type",
"instance_type",
"pricing_unit",
"region",
"estimate_category",
"rate_code_count",
"usage_electricity_consumption_kwh_per_pricing_unit_mean",
"total_tonnes_co2e_per_pricing_unit_mean",
"total_water_litres_per_pricing_unit_mean"
],
"records": [
{
"version": "meth-v5.2.0",
"line_item_product_code": "AmazonEC2",
"line_item_usage_type": "ATL1-BoxUsage:c5d.12xlarge",
"instance_type": "c5d.12xlarge",
"pricing_unit": "Hours",
"region": "us-east-1",
"estimate_category": "compute",
"rate_code_count": 22,
"usage_electricity_consumption_kwh_per_pricing_unit_mean": 0.149305241475978,
"total_tonnes_co2e_per_pricing_unit_mean": 0.0000638538545667879,
"total_water_litres_per_pricing_unit_mean": 0.371644220712589
}
]
}To enrich your own cloud data, match each row on product, region and pricing unit, then multiply the factor by your usage quantity. That is the same enrichment Greenpixie's managed service performs, run in your own environment. For a full worked example, see Enrich an AWS cloud usage report using the API.
The copied snippet embeds your live key. Before committing code, swap it for an environment variable or secret so the key never lands in source control.