> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Emissions Tools

> MCP tools for querying GHG emissions, historical trends, total impacts, and emission factors

# 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](#emission-categories) 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

<Warning>
  Never add emission values from different gases together. Each gas uses a different unit and represents a different substance — they are not additive.
</Warning>

| 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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<Accordion title="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       |
</Accordion>

## `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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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                         |

<Note>
  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.
</Note>

**Example response (grouped by scope):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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

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

## Related

<CardGroup cols={2}>
  <Card title="Facilities" icon="building" href="/mcp/facilities">
    Filter emissions by facility to see site-level breakdowns
  </Card>

  <Card title="Vehicles" icon="truck" href="/mcp/vehicles">
    Fleet data contributing to Scope 1 mobile combustion emissions
  </Card>

  <Card title="Dashboards" icon="chart-line" href="/mcp/dashboards">
    Pre-built dashboard views for emissions visualization
  </Card>

  <Card title="Decarbonization" icon="seedling" href="/mcp/decarb">
    Reduction targets and actions based on emission baselines
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/emissions/overview">
    REST API endpoints for emissions data
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/emissions-data">
    Query emissions from the command line
  </Card>
</CardGroup>