Intensity Metric Tools

Read and load intensity metrics — emissions per unit of activity (tCO₂e per litre bottled, per unit produced, per €M of revenue). A group defines the denominator: a free-text unit and the emission scopes that make up the numerator. Each record inside the group holds one period’s quantity, and the API returns the resulting value (emissions ÷ quantity) plus the delta against the previous period.

The numerator is the whole organization’s emissions. A single-site volume loaded onto a multi-site organization produces a misleading intensity — use the organization whose emissions match the volume.

Periods may not overlap inside a group, so a group holds either annual records or monthly ones — never both. Periods are immutable: delete and recreate a record to move it.

`list_intensity_metric_groups`

List the organization’s intensity metric groups. Start here to find the group_id the other tools need. Parameters:

Parameter	Type	Required	Default	Description
`filter_by`	string	No	—	Free-text filter on the group’s name or unit
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "page": 1,
  "size": 50,
  "total": 2,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "a1b2c3d4-...",
      "name": "Millón Litros producidos",
      "unit": "Millón Litros producidos",
      "scopes": [1, 2, 3],
      "status": "active",
      "is_grouping": false
    },
    {
      "id": "661f9511-f3ac-52e5-b827-557766551111",
      "organization_id": "a1b2c3d4-...",
      "name": "Revenue (€M)",
      "unit": "Revenue (€M)",
      "scopes": [1, 2],
      "status": "active",
      "is_grouping": true
    }
  ]
}

Key response fields:

Field	Description
`unit`	The denominator, free text — this is what the app displays
`scopes`	Which emission scopes make up the numerator
`is_grouping`	`true` for a group that aggregates child organizations’ groups instead of holding its own records

`get_intensity_metric_group`

Get one group by ID. Parameters:

Parameter	Type	Required	Default	Description
`group_id`	string	Yes	—	UUID of the group
`organization_id`	string	No	default org	Organization UUID

`list_intensity_metrics`

List the records in a group, each with its period, quantity, computed intensity and delta. Parameters:

Parameter	Type	Required	Default	Description
`group_id`	string	Yes	—	UUID of the group
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "page": 1,
  "size": 50,
  "total": 2,
  "items": [
    {
      "id": "a1b2c3d4-...",
      "intensity_metric_group_id": "550e8400-...",
      "start_date": "2025-01-01",
      "end_date": "2025-01-31",
      "quantity": 16.22,
      "value": 21.87,
      "delta": 0,
      "status": "active",
      "unit": "Millón Litros producidos",
      "scopes": [1, 2, 3]
    }
  ]
}

Key response fields:

Field	Description
`quantity`	The production volume for the period, in the group’s unit
`value`	The intensity: organization emissions ÷ quantity
`delta`	Change against the previous period

`get_intensity_metric`

Get one record by ID. Parameters:

Parameter	Type	Required	Default	Description
`metric_id`	string	Yes	—	UUID of the record
`organization_id`	string	No	default org	Organization UUID

`get_organization_intensity_metrics`

Every intensity value across all of the organization’s groups — the fastest way to see all intensities at once. Parameters:

Parameter	Type	Required	Default	Description
`start_date`	string	No	—	Period start (`YYYY-MM-DD`), must be paired with `end_date`
`end_date`	string	No	—	Period end (`YYYY-MM-DD`), must be paired with `start_date`
`organization_id`	string	No	default org	Organization UUID

This summary returns value and delta but not the underlying quantities. Use list_intensity_metrics when you need the volumes.

Example prompts:

"What are our intensity metrics for 2025?"
"Show me emissions per litre produced last year"
"Which of our intensity metrics got worse compared to the previous period?"
"List the intensity metric groups that have no data loaded yet"

`create_intensity_metric_group`

Create a group — the denominator definition. Create it once, then add one record per period. Parameters:

Parameter	Type	Required	Default	Description
`unit`	string	Yes	—	Denominator unit shown in the app (e.g. `"Millón Litros producidos"`)
`scopes`	integer[]	Yes	—	Scopes in the numerator
`name`	string	No	value of `unit`	Internal name
`is_grouping`	boolean	No	`false`	Aggregate child organizations’ groups instead of holding records
`organization_id`	string	No	default org	Organization UUID

scopes accepts only the combinations the API allows: [1], [2], [3], [1,2], [2,3], [1,2,3]. Anything else (e.g. [1,3]) is rejected before the request is sent.

`update_intensity_metric_group`

Update a group. Only provided fields are changed. Parameters:

Parameter	Type	Required	Default	Description
`group_id`	string	Yes	—	UUID of the group
`unit`	string	No	—	New unit
`name`	string	No	—	New internal name
`scopes`	integer[]	No	—	New scopes
`organization_id`	string	No	default org	Organization UUID

`delete_intensity_metric_group`

Delete a group and every record inside it. Parameters:

Parameter	Type	Required	Default	Description
`group_id`	string	Yes	—	UUID of the group
`organization_id`	string	No	default org	Organization UUID

The periods the group held stop contributing to dashboards and reports. Confirm with the user before calling this.

`create_intensity_metric`

Add a production volume for one period to a group. Parameters:

Parameter	Type	Required	Default	Description
`group_id`	string	Yes	—	UUID of the group the record belongs to
`start_date`	string	Yes	—	Period start, `YYYY-MM-DD` (inclusive)
`end_date`	string	Yes	—	Period end, `YYYY-MM-DD` (inclusive)
`quantity`	number	Yes	—	Volume in the group’s unit, greater than 0
`organization_id`	string	No	default org	Organization UUID

Returns the created record including the computed intensity value. An overlapping period is rejected with INTENSITY_METRICS_ALEADY_EXISTS_IN_THIS_PERIOD.

`update_intensity_metric`

Update a record’s quantity. Periods are immutable. Parameters:

Parameter	Type	Required	Default	Description
`metric_id`	string	Yes	—	UUID of the record
`quantity`	number	Yes	—	New volume, greater than 0
`organization_id`	string	No	default org	Organization UUID

`delete_intensity_metric`

Delete a record. Parameters:

Parameter	Type	Required	Default	Description
`metric_id`	string	Yes	—	UUID of the record
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Create an intensity metric for millions of litres produced, all three scopes"
"Load 224.058 million litres for 2025 into the litres-produced metric"
"Load these monthly production volumes for 2025: [pasted table]"
"Correct the March quantity to 17.51"

Workflow

Find the group — list_intensity_metric_groups, or create_intensity_metric_group if the denominator doesn’t exist yet
Check what’s loaded — list_intensity_metrics to see existing periods and avoid an overlap
Load periods — create_intensity_metric once per period, all with the same granularity
Verify — list_intensity_metrics for the group, or get_organization_intensity_metrics for everything at once

Limitations

Parent-level roll-up cannot be configured through these tools: a group can be created with is_grouping, but linking a parent grouping to its children’s groups is not exposed by the API yet.

Emissions

The numerator — GHG emissions these metrics divide

Organizations

The org tree, to pick the organization matching a volume

Custom KPIs

User-defined indicators collected through campaigns

CLI Intensity Metrics

The same operations from the command line

Getting Started

Tools Reference

Reference Data

Intensity Metric Tools

Intensity Metric Tools

`list_intensity_metric_groups`

`get_intensity_metric_group`

`list_intensity_metrics`

`get_intensity_metric`

`get_organization_intensity_metrics`

`create_intensity_metric_group`

`update_intensity_metric_group`

`delete_intensity_metric_group`

`create_intensity_metric`

`update_intensity_metric`

`delete_intensity_metric`

Workflow

Limitations

Emissions

Organizations

Custom KPIs

CLI Intensity Metrics

​Intensity Metric Tools

​list_intensity_metric_groups

​get_intensity_metric_group

​list_intensity_metrics

​get_intensity_metric

​get_organization_intensity_metrics

​create_intensity_metric_group

​update_intensity_metric_group

​delete_intensity_metric_group

​create_intensity_metric

​update_intensity_metric

​delete_intensity_metric

​Workflow

​Limitations

​Related

Emissions

Organizations

Custom KPIs

CLI Intensity Metrics

Intensity Metric Tools

`list_intensity_metric_groups`

`get_intensity_metric_group`

`list_intensity_metrics`

`get_intensity_metric`

`get_organization_intensity_metrics`

`create_intensity_metric_group`

`update_intensity_metric_group`

`delete_intensity_metric_group`

`create_intensity_metric`

`update_intensity_metric`

`delete_intensity_metric`

Workflow

Limitations

Related