Emissions Tools

Query greenhouse gas emissions data — validated GHG emissions by scope and category, year-over-year historical trends, aggregated total impacts, use-of-sold-product emissions (Scope 3 Category 11), and the emission factors applied to calculations. All emission values follow the GHG Protocol framework across Scope 1 (direct), Scope 2 (energy), and Scope 3 (value chain).

`get_greenhouse_gas_emissions`

Query validated GHG emissions across all 26 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:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`category`	string	No	`null`	Emission category. Omit to query all 26 categories at once. See valid values below.
`aggregate`	boolean	No	`true`	`true` for aggregated totals grouped by non-pinned dimensions; `false` for paginated raw rows
`scope`	integer	No	`null`	GHG Protocol scope: `1`, `2`, or `3`
`date_from`	string	No	`null`	Start date inclusive (YYYY-MM-DD)
`date_to`	string	No	`null`	End date inclusive (YYYY-MM-DD)
`facility_id`	string	No	`null`	Filter by facility UUID
`vehicle_id`	string	No	`null`	Filter by vehicle UUID
`ghg_gas`	string	No	`null`	Filter by gas type: `co2e`, `co2`, `ch4`, or `n2o`
`limit`	integer	No	`100`	Max rows in raw mode (1–500)
`offset`	integer	No	`0`	Row 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.

Gas	Unit	Description
`co2e`	kg	CO₂-equivalent — use this for standard scope totals
`co2`	kg	Carbon dioxide
`ch4`	g	Methane
`n2o`	g	Nitrous 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
  }
}

Key response fields:

Field	Description
`mode`	`aggregate` or `raw` depending on the `aggregate` parameter
`group_by`	Dimensions used as grouping keys (dimensions not pinned by filters)
`rows[].total_emissions`	Sum of emissions for that group
`rows[].count`	Number of records aggregated into this row
`totals_by_ghg_gas`	Grand totals keyed by gas type (e.g. `{"co2e": 500.0, "ch4": 20.0}`)

Raw Mode Response

When aggregate=false, returns paginated individual emission records. Use limit and offset for pagination.

{
  "category": "electricity",
  "mode": "raw",
  "rows": [
    {
      "id": "ti-1a2b3c4d-...",
      "organization_id": "a1b2c3d4-...",
      "emission_source_id": "es-5e6f7a8b-...",
      "scope": 2,
      "category": "electricity",
      "date": "2024-06-15T00:00:00",
      "emissions_per_day": 1.37,
      "ghg_gas": "co2e",
      "ghg_type": 0,
      "ipcc": "4.D",
      "enabled": true,
      "facility_id": "fac-9c0d1e2f-...",
      "vehicle_id": null,
      "created_at": "2024-07-01T10:00:00",
      "updated_at": "2024-07-01T10:00:00"
    }
  ],
  "total_count": 1842,
  "limit": 100,
  "offset": 0
}

Emission Categories

All 26 categories

Category	Typical scope
`capex`	Scope 3
`electricity`	Scope 2
`electricity_generation`	Scope 3
`electricity_transmission_and_distribution`	Scope 3
`employees_in_itinere`	Scope 3
`employees_in_labore`	Scope 3
`land_use_change`	Scope 1
`process`	Scope 1
`purchases`	Scope 3
`recharge`	Scope 1
`stationary`	Scope 1
`stationary_generation`	Scope 3
`transport`	Scope 1
`transport_distribution_downstream`	Scope 3
`transport_distribution_upstream`	Scope 3
`transport_generation`	Scope 3
`travels`	Scope 3
`use_of_product_combustion`	Scope 3
`use_of_product_electricity`	Scope 3
`use_of_product_water`	Scope 3
`waste_water_treatment_discharge`	Scope 3
`waste_water_treatment_population`	Scope 3
`waste_water_treatment_sludge`	Scope 3
`waste_water_treatment_water`	Scope 3
`wastes`	Scope 3
`water`	Scope 3

`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, aggregated by product. Parameters:

Parameter	Type	Required	Default	Description
`start_date`	string	Yes	—	Start date (YYYY-MM-DD)
`end_date`	string	Yes	—	End date (YYYY-MM-DD). Max range: 2 years.
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "items": [
    {
      "product_name": "Gas Boiler Model X",
      "units_sold": 1200.0,
      "co2e": 85.4
    },
    {
      "product_name": "Electric Heater Y",
      "units_sold": 3500.0,
      "co2e": 42.1
    }
  ]
}

Key response fields:

Field	Description
`product_name`	Name of the sold product
`units_sold`	Total units sold in the period
`co2e`	Total CO2e emissions in tonnes from product use

`get_historical_emissions`

Get year-over-year historical emissions for an organization. Returns manually entered emission records used for tracking trends before Dcycle was adopted, or for periods not covered by automated data collection. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "items": [
    {
      "id": "he-1a2b3c4d-...",
      "organization_id": "a1b2c3d4-...",
      "start_date": "2022-01-01",
      "end_date": "2022-12-31",
      "scope": 1,
      "category": "transport",
      "total_co2e": 245.8,
      "description": "Fleet fuel consumption from manual records",
      "ghg_gas": "co2e",
      "ghg_type": 0,
      "enabled": true,
      "co2e": 245.8,
      "created_at": "2024-01-15T10:00:00",
      "updated_at": null
    },
    {
      "id": "he-5e6f7a8b-...",
      "organization_id": "a1b2c3d4-...",
      "start_date": "2022-01-01",
      "end_date": "2022-12-31",
      "scope": 2,
      "category": "electricity",
      "total_co2e": 890.2,
      "description": null,
      "ghg_gas": "co2e",
      "ghg_type": 0,
      "enabled": true,
      "co2e": 890.2,
      "created_at": "2024-01-15T10:00:00",
      "updated_at": null
    }
  ],
  "total": 2
}

Key response fields:

Field	Description
`start_date` / `end_date`	The emission period this record covers
`scope`	GHG Protocol scope (1, 2, or 3)
`category`	Emission category (e.g. `transport`, `electricity`, `purchases`)
`total_co2e`	Total CO2e in kg for this record
`co2e`	Calculated CO2e from total_impacts (null if not calculated)
`ghg_type`	`0` = fossil, `1` = biomass
`enabled`	Whether this entry is active in calculations

`get_total_impacts`

Get aggregated total impacts across all scopes, with optional grouping and date filters. Returns a high-level summary useful for dashboards and quick overviews. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`start_date`	string	No	—	Start date (YYYY-MM-DD)
`end_date`	string	No	—	End date (YYYY-MM-DD)
`group_by`	string	No	—	Grouping dimension: `SCOPE`, `CATEGORY`, or `MONTH`
`include_children`	boolean	No	`false`	Include child organizations

For detailed validated emissions with flexible filtering, use get_greenhouse_gas_emissions instead — it queries the authoritative validated views. get_total_impacts is best for quick high-level summaries.

Example response (grouped by scope):

{
  "organization_id": "a1b2c3d4-...",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "unit": "tCO2e",
  "total_co2e": 3456.7,
  "items": [
    { "scope": 1, "co2e": 450.2 },
    { "scope": 2, "co2e": 890.5 },
    { "scope": 3, "co2e": 2116.0 }
  ]
}

Example response (grouped by category):

{
  "organization_id": "a1b2c3d4-...",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "unit": "tCO2e",
  "total_co2e": 3456.7,
  "items": [
    { "scope": 1, "category": "transport", "co2e": 320.1 },
    { "scope": 2, "category": "electricity", "co2e": 890.5 },
    { "scope": 3, "category": "purchases", "co2e": 1580.3 }
  ]
}

Key response fields:

Field	Description
`unit`	Always `tCO2e` (tonnes of CO2-equivalent)
`total_co2e`	Grand total across all items
`items`	Breakdown by the chosen `group_by` dimension
`items[].scope`	GHG scope (present in all groupings)
`items[].category`	Emission category (only when `group_by=CATEGORY`)
`items[].year` / `month`	Time period (only when `group_by=MONTH`)

`list_emission_factors`

List the emission factors currently used by the organization in its calculations. Useful for auditing methodology and understanding which conversion factors are applied to each data category. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`start_date`	string	No	—	Filter by period start (YYYY-MM-DD)
`end_date`	string	No	—	Filter by period end (YYYY-MM-DD)
`category`	string	No	—	Emission category filter
`include_children`	boolean	No	`false`	Include child organization emission factors

Example response:

[
  {
    "category": "electricity",
    "source": "electricity",
    "location": "Spain",
    "unit_name": "kWh",
    "ghg_type": "co2",
    "ef_source": "IEA 2023",
    "ef": 0.187
  },
  {
    "category": "transport",
    "source": "fuel",
    "location": "Europe",
    "unit_name": "litre",
    "ghg_type": "co2e",
    "ef_source": "DEFRA 2024",
    "ef": 2.31
  }
]

Key response fields:

Field	Description
`category`	Emission category this factor applies to
`source`	Data source type (e.g. `electricity`, `fuel`, `business_travel`)
`location`	Geographic context for the factor
`ef`	The emission factor value
`ef_source`	Database origin (e.g. `IEA 2023`, `DEFRA 2024`, `Ecoinvent 3.8`)
`ghg_type`	Gas type: `co2`, `co2e`, `ch4`, or `n2o`

Example prompts:

"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"
"What are our use-of-product emissions for 2024?"
"How have our emissions changed year over year?"
"What are our total impacts for 2025 grouped by scope?"
"Show total emissions including subsidiaries"
"What emission factors are we using for electricity?"

Workflow

Quick overview — get_total_impacts with group_by=SCOPE for a high-level scope 1/2/3 breakdown
Detailed analysis — get_greenhouse_gas_emissions with scope or category filters for validated granular data
Track trends — get_historical_emissions to see year-over-year patterns including pre-Dcycle periods
Drill into products — get_use_of_product_emissions for Scope 3 Category 11 product-level detail
Audit methodology — list_emission_factors to see which conversion factors are applied

Facilities

Filter emissions by facility to see site-level breakdowns

Vehicles

Fleet data contributing to Scope 1 mobile combustion emissions

Dashboards

Pre-built dashboard views for emissions visualization

Decarbonization

Reduction targets and actions based on emission baselines

API Reference

REST API endpoints for emissions data

CLI

Query emissions from the command line

Getting Started

Tools Reference

Reference Data

Emissions Tools

Emissions Tools

`get_greenhouse_gas_emissions`

GHG Gas Units

Aggregate Mode Response

Raw Mode Response

Emission Categories

`get_use_of_product_emissions`

`get_historical_emissions`

`get_total_impacts`

`list_emission_factors`

Workflow

Facilities

Vehicles

Dashboards

Decarbonization

API Reference

CLI

​Emissions Tools

​get_greenhouse_gas_emissions

​GHG Gas Units

​Aggregate Mode Response

​Raw Mode Response

​Emission Categories

​get_use_of_product_emissions

​get_historical_emissions

​get_total_impacts

​list_emission_factors

​Workflow

​Related

Facilities

Vehicles

Dashboards

Decarbonization

API Reference

CLI

Emissions Tools

`get_greenhouse_gas_emissions`

GHG Gas Units

Aggregate Mode Response

Raw Mode Response

Emission Categories

`get_use_of_product_emissions`

`get_historical_emissions`

`get_total_impacts`

`list_emission_factors`

Workflow

Related