Skip to main content

​
Emissions Tools

Tools for querying aggregated emissions data.

​
get_greenhouse_gas_emissions

Query validated GHG emissions across all 25 emission categories. Only records with a fully valid and enabled emission source chain are included — these are the authoritative figures to use for reporting, analysis, and visualizations. Parameters:
ParameterTypeRequiredDefaultDescription
organization_idstringYes—UUID of the organization
categorystringNonullEmission category. Omit to query all 25 categories at once. See valid values below.
aggregatebooleanNotruetrue for aggregated totals grouped by non-pinned dimensions; false for paginated raw rows
scopeintegerNonullGHG Protocol scope: 1, 2, or 3
date_fromstringNonullStart date inclusive (YYYY-MM-DD)
date_tostringNonullEnd date inclusive (YYYY-MM-DD)
facility_idstringNonullFilter by facility UUID
vehicle_idstringNonullFilter by vehicle UUID
ghg_gasstringNonullFilter by gas type: co2e, co2, ch4, or n2o
limitintegerNo100Max rows in raw mode (1–500)
offsetintegerNo0Row offset for raw mode pagination

​
GHG Gas Units

Never add emission values from different gases together. Each gas uses a different unit and represents a different substance — they are not additive.
GasUnitDescription
co2ekgCO₂-equivalent — use this for standard scope totals
co2kgCarbon dioxide
ch4gMethane
n2ogNitrous oxide
For example, totals_by_ghg_gas["co2e"] = 500.0 means 500 kg of CO₂-equivalent, while totals_by_ghg_gas["ch4"] = 20.0 means 20 g of methane. These cannot be summed.

​
Aggregate Mode Response

When aggregate=true (default), the response groups results by all dimensions not fixed by a filter. Unfiltered dimensions become grouping keys: category, scope, ghg_gas, facility_id, vehicle_id. 
{
  "category": "electricity",
  "mode": "aggregate",
  "group_by": ["scope", "ghg_gas"],
  "rows": [
    { "scope": 2, "ghg_gas": "co2e", "total_emissions": 500.0, "count": 12 },
    { "scope": 2, "ghg_gas": "ch4",  "total_emissions": 20.0,  "count": 12 }
  ],
  "totals_by_ghg_gas": {
    "co2e": 500.0,
    "ch4": 20.0
  }
}

​
Emission Categories

CategoryTypical scope
capexScope 3
electricityScope 2
electricity_generationScope 3
electricity_transmission_and_distributionScope 3
employees_in_itinereScope 3
employees_in_laboreScope 3
processScope 1
purchasesScope 3
rechargeScope 1
stationaryScope 1
stationary_generationScope 3
transportScope 1
transport_distribution_downstreamScope 3
transport_distribution_upstreamScope 3
transport_generationScope 3
travelsScope 3
use_of_product_combustionScope 3
use_of_product_electricityScope 3
use_of_product_waterScope 3
waste_water_treatment_dischargeScope 3
waste_water_treatment_populationScope 3
waste_water_treatment_sludgeScope 3
waste_water_treatment_waterScope 3
wastesScope 3
waterScope 3
Example queries: 
"What are our total scope 1 emissions in 2025?"
"Break down electricity emissions by facility for Q1 2024"
"Show CO₂-equivalent emissions for purchases last year"
"Give me all scope 3 categories for this organization in 2024"

​
get_use_of_product_emissions

Get Scope 3 Category 11 — “Use of Sold Products” emissions. Shows the emissions generated when customers use the products you sell. Parameters:
ParameterTypeRequiredDescription
start_datestringYesStart date (YYYY-MM-DD)
end_datestringYesEnd date (YYYY-MM-DD). Max range: 2 years.
organization_idstringNoUUID of the organization
Example queries: 
"What are our use-of-product emissions for 2024?"
"Show Scope 3 sold products emissions"