Waste Tools

Query waste records for facilities — including waste types, quantities, treatment methods, transport distances, and CO₂e emissions. This is Scope 3 Category 5 (waste generated in operations) data.

`list_wastes`

List waste records for a specific facility.

facility_id is required — call list_facilities first to get valid IDs.

Parameters:

Parameter	Type	Required	Default	Description
`facility_id`	string	Yes	—	UUID of the facility
`organization_id`	string	No	default org	Organization UUID
`status`	string	No	—	Status filter: `active`, `deleted`
`start_date`	string	No	—	Filter from this date (YYYY-MM-DD)
`end_date`	string	No	—	Filter until this date (YYYY-MM-DD)
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page

Example response:

{
  "items": [
    {
      "id": "550e8400-...",
      "identification_name": "RSU-2024-001",
      "description": "Municipal solid waste from office building",
      "status": "active",
      "start_date": "2024-01-01",
      "end_date": "2024-03-31",
      "facility_id": "660e8400-...",
      "quantity": 1500.0,
      "total_km_to_waste_center": 25.0,
      "low_code": "20 03 01",
      "rd_code": "D1",
      "co2e": 312.5,
      "co2e_biomass": 0.0,
      "unit": {
        "id": "61743a63-...",
        "name": "kilogram_(kg)",
        "type": "weight"
      },
      "created_at": "2024-11-24T10:30:00Z"
    }
  ],
  "total": 23,
  "page": 1,
  "size": 50,
  "pages": 1
}

Key response fields:

Field	Description
`identification_name`	Internal reference code for the waste record
`quantity`	Amount of waste in the unit specified by `unit.name`
`low_code`	European Waste Catalogue (EWC/LER) code classifying the waste type
`rd_code`	Recovery (R) or Disposal (D) operation code
`total_km_to_waste_center`	Distance to the waste treatment center in km
`co2e`	Calculated CO₂e emissions in kg
`co2e_biomass`	CO₂e from biomass sources in kg
`unit`	Measurement unit (e.g. `kilogram_(kg)`, `tonne_(t)`)

Example prompts:

"Show waste records for our Madrid factory"
"What waste did facility abc-123 generate in 2024?"
"List active waste records for Q1 2025"
"How much CO₂ comes from our waste in each facility?"

Write Operations

`create_waste`

Create a waste record for Scope 3 Category 5 (waste generated in operations). Each record belongs to a facility and covers a date range. CO₂e is calculated asynchronously after creation — the response will initially show co2e as null. Parameters:

Parameter	Type	Required	Default	Description
`facility_id`	string	Yes	—	UUID of the facility. Use `list_facilities` to find IDs
`identification_name`	string	Yes	—	Waste name or invoice reference (e.g. “RSU-2024-Q1”)
`start_date`	string	Yes	—	Start of waste period (`YYYY-MM-DD`)
`end_date`	string	Yes	—	End of waste period (`YYYY-MM-DD`)
`base_quantity`	number	Yes	—	Waste quantity (must be > 0). Defaults to kg if no `unit_id`
`description`	string	No	`""`	Description of the waste
`destination`	string	No	`""`	Waste destination or treatment facility name
`total_km_to_waste_center`	number	No	`0`	Distance to waste treatment center in km (>= 0)
`unit_id`	string	No	kg	UUID of the quantity unit (e.g. kg, tonne)
`waste_efs_id`	string	No	—	UUID of a waste emission factor (LER + RD code combo)
`custom_emission_factor_id`	string	No	—	UUID of a custom emission factor override
`organization_id`	string	No	default org	Organization UUID

To find valid waste_efs_id values, use the REST API endpoint GET /v1/waste-efs which lists available LER code + RD code combinations with their UUIDs.

CO₂e emissions are calculated in the background after creation. The initial response will show co2e: null. Call list_wastes after a few seconds to see the calculated value.

Example response:

{
  "id": "550e8400-...",
  "identification_name": "RSU-2024-Q1",
  "description": "Municipal solid waste",
  "status": "active",
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "base_quantity": 1500.0,
  "quantity": 1500.0,
  "total_km_to_waste_center": 25.0,
  "destination": "EcoWaste Treatment Plant",
  "co2e": null,
  "co2e_biomass": 0.0,
  "created_at": "2025-07-09T10:30:00Z"
}

Example prompts:

"Log 1500 kg of municipal waste for our Madrid factory, Q1 2024"
"Create a waste record for hazardous solvents, 250 kg, facility abc-123"
"Record 3 tonnes of packaging waste for January-March 2025"
"Add a waste entry for our Barcelona office, 800 kg, destination EcoWaste Plant"

Common errors:

Error	Cause
422: “facility_id not found”	Invalid facility UUID
422: “base_quantity must be > 0”	Zero or negative quantity
422: “unit_id not found”	Invalid unit UUID

`update_waste`

Update an existing waste record. Only the fields you provide are changed. CO₂e is recalculated after update. Parameters:

Parameter	Type	Required	Default	Description
`waste_id`	string	Yes	—	UUID of the record. Use `list_wastes` to find it
`identification_name`	string	No	—	New waste name or invoice reference
`description`	string	No	—	New description
`start_date`	string	No	—	New start date (`YYYY-MM-DD`)
`end_date`	string	No	—	New end date (`YYYY-MM-DD`)
`base_quantity`	number	No	—	New waste quantity (> 0)
`destination`	string	No	—	New waste destination or treatment facility
`total_km_to_waste_center`	number	No	—	New distance to waste center in km (>= 0)
`unit_id`	string	No	—	New quantity unit UUID
`waste_efs_id`	string	No	—	New waste emission factor UUID
`custom_emission_factor_id`	string	No	—	New custom emission factor UUID
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Change waste w1 quantity to 2000 kg"
"Update the destination of waste abc to 'EcoWaste Plant'"
"Fix the dates on waste record xyz to Q2 2025"

Common errors:

Error	Cause
404: “Waste not found”	Invalid waste UUID
422: “base_quantity must be > 0”	Zero or negative quantity

Workflows

Querying waste records

Find facilities — list_facilities to discover facility IDs
List waste records — list_wastes with the facility_id
View emissions — get_greenhouse_gas_emissions with category=wastes for aggregated waste emission totals

Logging waste

Find facility — list_facilities to get the facility_id
Create waste — create_waste with facility, identification, dates, and quantity
Verify — list_wastes to confirm it appears and check CO₂e calculation status

API: List Wastes

REST API equivalent with additional filters

Facilities

Find facility IDs to query waste records

Emissions

Aggregated Scope 3 waste emissions

CLI

Manage waste records from the command line

​Waste Tools

​list_wastes

​Write Operations

​create_waste

​update_waste

​Workflows

​Querying waste records

​Logging waste

​Related

API: List Wastes

Facilities

Emissions

CLI

Waste Tools

`list_wastes`

Write Operations

`create_waste`

`update_waste`

Workflows

Querying waste records

Logging waste

Related