Carbon Accounting Use Case
Read your GHG Scope 1-3 emissions from Coolset for reporting, dashboards and analysis.
Overview
The Carbon API gives read access to the emissions Coolset calculates for your workspace. Use it for:
- Sustainability reporting (CSRD, GHG Protocol)
- Internal carbon tracking and dashboards
- Exporting line-level data to your own tools
All carbon endpoints are served from:
https://developers.coolset.com/api
Carbon Data Flow
Totals and trends: /emission_calculations/charts/
Use the charts endpoint for almost every "how much did we emit" question. It aggregates emissions by the dimensions you choose with group_by.
Totals per scope for a year
curl "https://developers.coolset.com/api/emission_calculations/charts/?group_by=scope&accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31" \
-H "Authorization: ApiKey YOUR_API_TOKEN"
{
"count": 2,
"next": null,
"previous": null,
"results": [
{ "scope": "3", "total_co2_kg": 52127747.07, "emission_count": 56710, "transaction_count": 55755 },
{ "scope": "2", "total_co2_kg": 917.15, "emission_count": 3, "transaction_count": 0 }
]
}
Monthly trend
Group by date and set delimit_by to daily, monthly or yearly:
curl "https://developers.coolset.com/api/emission_calculations/charts/?group_by=date&delimit_by=monthly&accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31" \
-H "Authorization: ApiKey YOUR_API_TOKEN"
{
"count": 12,
"next": null,
"previous": null,
"results": [
{ "date": "2025-01-01T00:00:00Z", "total_co2_kg": 10063.01, "emission_count": 94, "transaction_count": 27 },
{ "date": "2025-02-01T00:00:00Z", "total_co2_kg": 7706.47, "emission_count": 84, "transaction_count": 18 }
]
}
group_by accepts one or more of: scope, date, ghg_category_name, category_name, sub_category_name, classification_category_name, vendor_name, title, is_activity_based, main_emission. Repeat the parameter to group by several, for example group_by=scope&group_by=ghg_category_name.
Sort with ordering, for example ordering=-total_co2_kg for the largest first.
Line items: /emission_calculations/emissions/
Use the emissions list when you need the individual records behind the totals.
curl "https://developers.coolset.com/api/emission_calculations/emissions/?accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31&scope=3&limit=100" \
-H "Authorization: ApiKey YOUR_API_TOKEN"
{
"count": 56713,
"next": "https://developers.coolset.com/api/emission_calculations/emissions/?accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31&limit=100&offset=100&scope=3",
"previous": null,
"results": [
{
"id": 946531,
"title": "452000 - Consultancy",
"description": "Invoice 138",
"vendor_name": null,
"accounting_date": "2025-12-31T00:00:00Z",
"scope": "3",
"ghg_category_name": "Capital goods",
"category_name": "Equipment",
"sub_category_name": "Machinery",
"co2_kg": 1572.68,
"volume": 6050.0,
"volume_unit": "EUR",
"classification_source": "manual",
"confidence_status": "confident"
}
]
}
Useful filters:
| Parameter | Example | Notes |
|---|---|---|
accounting_date__gte, accounting_date__lte | 2025-01-01 | Date range |
scope | 1, 2, 3, Excluded, Offset | |
ghg_category_id, category_id, sub_category_id | 120 | IDs from the emission factor endpoints |
search | travel | Free-text search |
ordering | -co2_kg | Prefix with - for descending |
Export as CSV: /emission_calculations/emissions/export/
Takes the same filters as the emissions list and streams a CSV file:
curl "https://developers.coolset.com/api/emission_calculations/emissions/export/?accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31" \
-H "Authorization: ApiKey YOUR_API_TOKEN" \
--output emissions-2025.csv
Complete Example: Python
import requests
BASE_URL = "https://developers.coolset.com/api"
HEADERS = {"Authorization": "ApiKey YOUR_API_TOKEN"}
def totals_by_scope(year):
"""Total kg CO2e per scope for a calendar year."""
response = requests.get(
f"{BASE_URL}/emission_calculations/charts/",
headers=HEADERS,
params={
"group_by": "scope",
"accounting_date__gte": f"{year}-01-01",
"accounting_date__lte": f"{year}-12-31",
},
)
response.raise_for_status()
return {row["scope"]: row["total_co2_kg"] for row in response.json()["results"]}
def monthly_trend(year):
"""Total kg CO2e per month for a calendar year."""
response = requests.get(
f"{BASE_URL}/emission_calculations/charts/",
headers=HEADERS,
params={
"group_by": "date",
"delimit_by": "monthly",
"accounting_date__gte": f"{year}-01-01",
"accounting_date__lte": f"{year}-12-31",
},
)
response.raise_for_status()
return [(row["date"][:7], row["total_co2_kg"]) for row in response.json()["results"]]
def all_emissions(year):
"""Every emission line item for a year, following pagination."""
url = f"{BASE_URL}/emission_calculations/emissions/"
params = {
"accounting_date__gte": f"{year}-01-01",
"accounting_date__lte": f"{year}-12-31",
"limit": 100,
}
while url:
response = requests.get(url, headers=HEADERS, params=params)
response.raise_for_status()
page = response.json()
yield from page["results"]
url, params = page["next"], None # `next` already carries the query
def export_csv(year, filename):
response = requests.get(
f"{BASE_URL}/emission_calculations/emissions/export/",
headers=HEADERS,
params={
"accounting_date__gte": f"{year}-01-01",
"accounting_date__lte": f"{year}-12-31",
},
)
response.raise_for_status()
with open(filename, "wb") as f:
f.write(response.content)
scopes = totals_by_scope(2025)
for scope, kg in sorted(scopes.items()):
print(f"Scope {scope}: {kg / 1000:,.1f} tCO2e")
Best Practices
Use charts for totals
Summing line items yourself is slow and can drift from what Coolset shows. Ask /emission_calculations/charts/ for the aggregation you need.
Units
co2_kg and total_co2_kg are kilograms of CO2e. Divide by 1,000 for tonnes.
Cache results
Emissions change when transactions are imported or reclassified, not continuously. Caching chart results for a few hours is usually fine.
API Endpoints Used
GET /emission_calculations/charts/- Carbon APIGET /emission_calculations/emissions/- Carbon APIGET /emission_calculations/emissions/export/- Carbon API
