List Wastes - Dcycle Platform Docs

List Wastes

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/wastes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/wastes"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "type": "<string>",
    "identification_name": "<string>",
    "invoice_id": "<string>",
    "description": "<string>",
    "status": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "facility_id": {},
    "base_quantity": 123,
    "quantity": 123,
    "percentage": {},
    "total_km_to_waste_center": 123,
    "low_code": {},
    "rd_code": {},
    "co2e": {},
    "co2e_biomass": 123,
    "custom_emission_factor_id": {},
    "custom_emission_factor": {},
    "unit": {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    },
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "prefix": {},
      "phone_number": {},
      "onboarding_done": {},
      "profile_img_url": {}
    },
    "uploaded_by": {},
    "source_invoice_id": "<string>",
    "source": {},
    "file_id": {},
    "file_name": {},
    "file_url": {},
    "error_messages": {},
    "linked_projects": {},
    "facility_percentages": {},
    "created_at": {},
    "updated_at": {},
    "confidence": {}
  },
  "total": 123,
  "total2": 123,
  "total_general": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true
}

GET

wastes

List Wastes

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/wastes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/wastes"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "type": "<string>",
    "identification_name": "<string>",
    "invoice_id": "<string>",
    "description": "<string>",
    "status": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "facility_id": {},
    "base_quantity": 123,
    "quantity": 123,
    "percentage": {},
    "total_km_to_waste_center": 123,
    "low_code": {},
    "rd_code": {},
    "co2e": {},
    "co2e_biomass": 123,
    "custom_emission_factor_id": {},
    "custom_emission_factor": {},
    "unit": {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    },
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "prefix": {},
      "phone_number": {},
      "onboarding_done": {},
      "profile_img_url": {}
    },
    "uploaded_by": {},
    "source_invoice_id": "<string>",
    "source": {},
    "file_id": {},
    "file_name": {},
    "file_url": {},
    "error_messages": {},
    "linked_projects": {},
    "facility_percentages": {},
    "created_at": {},
    "updated_at": {},
    "confidence": {}
  },
  "total": 123,
  "total2": 123,
  "total_general": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true
}

← Wastes API Retrieve a paginated list of waste disposal records for a specific facility. Each record includes enriched data: CO2e emissions, emission factor codes (LER/RD), linked projects, unit details, and the user who uploaded it.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

string

required

UUID of the facility to retrieve waste records forExample: 660e8400-e29b-41d4-a716-446655440000

array[string]

Filter by waste record status. Can be specified multiple times.Available values: uploaded, active, loading, review, error (see the status of Get Waste)Example: status[]=active&status[]=uploaded

date

Filter records with a start date on or after this date (ISO 8601)Example: 2024-01-01

date

Filter records with an end date on or before this date (ISO 8601)Example: 2024-12-31

array[string]

Filter by linked file UUID. Can be specified multiple times.Example: file_id[]=550e8400-e29b-41d4-a716-446655440000

datetime

Filter records created on or after this timestamp (ISO 8601)Example: 2024-01-01T00:00:00Z

datetime

Filter records created on or before this timestamp (ISO 8601)Example: 2024-12-31T23:59:59Z

string

Filter by CO2e calculation statusAvailable values: calculated, not_calculatedExample: co2e_status=calculated

array[string]

Filter by waste identification name. Can be specified multiple times.Example: identification_name[]=RSU-2024-001

array[string]

Filter by LER (European List of Waste) code, written as List LER Codes returns it: six digits with no spaces, with the trailing * of a hazardous waste. The code must match exactly. Can be specified multiple times.Example: ler_code[]=150101&ler_code[]=130205*

array[string]

Filter by R/D (recovery/disposal) code, written as List R/D Codes returns it: two digits (R01, not R1). The code must match exactly. Can be specified multiple times.Example: rd_code[]=R01

string

Filter by project UUIDExample: 770e8400-e29b-41d4-a716-446655440000

string

Sort field. Prefix with - for descending order.Example: -start_date (most recent first), identification_name

integer

default:"1"

Page number for paginationExample: 1

integer

default:"50"

Number of items per page (max 100)Example: 50

Response

array[object]

Array of waste record objects

Show Waste Object

string

Unique identifier (UUID) for the waste record

string

Always "wastes"

string

Waste identification name or invoice/delivery-note number, as sent on create

string

The same value as identification_name, under the name the other record types use

string

Description of the waste

string

Processing status: uploaded, active, loading, review or error, as described in Get Waste

date

Start date of the waste period

date

End date of the waste period

string | null

UUID of the facility this waste belongs to

number

Original waste quantity in the specified unit

number

Effective quantity after applying the facility percentage factor

number | null

Percentage factor applied to base quantity when split across facilities (0–1)

number

Distance to waste treatment center in kilometers

string | null

The waste’s LER (European List of Waste) code, as List LER Codes writes it: six digits with no spaces (200301, 130205*). The field keeps the name of the older LoW (List of Waste) catalog. null when the waste has no LER code (sent with only a description or a custom factor). A waste priced from the older emission factor catalog may carry that catalog’s key, prefixed with its source (DEFRA_2024-150101)

string | null

The waste’s R/D (recovery/disposal) code, two digits (D01, R03). null when the waste has no treatment code

number | null

CO2 equivalent emissions in kg CO2e. Populated asynchronously after record activation.

number

Biogenic CO2 emissions in kg CO2e

string | null

UUID of the custom emission factor, if used instead of the standard one

object | null

Full custom emission factor object if one is linked

object | null

Unit of measurement for the waste quantity

Show Unit Object

string

Unit UUID

string

Unit name (e.g., "kilogram_(kg)", "tonne_(t)")

string

Unit category (e.g., "weight")

object | null

User who uploaded or created the record

Show User Object

string

User UUID

string

First name

string

Last name

string

Email address

string | null

Phone prefix

string | null

Phone number

boolean | null

Whether the user has completed onboarding

string | null

Profile image URL

string | null

UUID of the user who created the record

string

Id of the waste’s group: every share of a waste split across facilities carries the id of the first share, the entity_id its ingest job item returns. A waste of a single facility carries its own id

string | null

Where the waste comes from: manual (a form or the API), pdf (read from a document) or bulk_file (a spreadsheet import). null on older wastes created by hand or through the API. Every share of a split waste has the same one

string | null

UUID of the linked file (if uploaded via bulk import)

string | null

Name of the linked import file

string | null

Download URL for the linked import file

array[string] | null

List of error messages if status is error

array[object]

Projects this waste record is linked to

array[object]

Facility distribution breakdown when a record is split across multiple facilities

datetime

Timestamp when the record was created

datetime | null

Timestamp when the record was last updated

object | null

Per-field OCR confidence scores. Only present for records uploaded via PDF.Example: {"waste_type": 0.95, "quantity": 0.82}

integer

Total active and uploaded waste records in the facility (facility-wide counter, independent of filters)

integer

Number of waste records currently being processed (loading status) in the facility

integer

Total records matching the current filters — use this for pagination calculations

integer

Current page number

integer

Number of items per page

string

Hash of the current filter state. Passed to Bulk Delete by Filters to confirm the filters haven’t changed between listing and deleting.

boolean

Capability flag: true means this backend exposes the bulk-*-by-filters endpoint for this list, so the client may offer “select all matching”. false on a backend that only supports bulk delete by explicit ids.

Example

curl -X GET "https://api.dcycle.io/v1/wastes?facility_id=660e8400-e29b-41d4-a716-446655440000&status[]=active&page=1&size=50" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

params = {
    "facility_id": "660e8400-e29b-41d4-a716-446655440000",
    "status[]": ["active"],
    "page": 1,
    "size": 50
}

response = requests.get(
    "https://api.dcycle.io/v1/wastes",
    headers=headers,
    params=params
)

result = response.json()
for waste in result["items"]:
    print(f"{waste['identification_name']}: {waste['co2e']} kg CO2e")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

const params = {
  facility_id: '660e8400-e29b-41d4-a716-446655440000',
  'status[]': ['active'],
  page: 1,
  size: 50
};

axios.get('https://api.dcycle.io/v1/wastes', { headers, params })
  .then(response => {
    response.data.items.forEach(waste => {
      console.log(`${waste.identification_name}: ${waste.co2e} kg CO2e`);
    });
  })
  .catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "wastes",
      "identification_name": "RSU-2024-001",
      "invoice_id": "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-e29b-41d4-a716-446655440000",
      "base_quantity": 1500.0,
      "quantity": 1500.0,
      "percentage": 1.0,
      "total_km_to_waste_center": 25.0,
      "low_code": "200301",
      "rd_code": "D01",
      "co2e": 312.5,
      "co2e_biomass": 0.0,
      "custom_emission_factor_id": null,
      "custom_emission_factor": null,
      "unit": {
        "id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
        "name": "kilogram_(kg)",
        "type": "weight"
      },
      "user": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "first_name": "Ana",
        "last_name": "García",
        "email": "ana.garcia@company.com",
        "prefix": null,
        "phone_number": null,
        "onboarding_done": true,
        "profile_img_url": null
      },
      "uploaded_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source_invoice_id": "550e8400-e29b-41d4-a716-446655440000",
      "source": "manual",
      "file_id": null,
      "file_name": null,
      "file_url": null,
      "error_messages": null,
      "linked_projects": [],
      "facility_percentages": [],
      "created_at": "2024-11-24T10:30:00Z",
      "updated_at": "2024-11-24T10:30:00Z",
      "confidence": null
    }
  ],
  "total": 47,
  "total2": 3,
  "total_general": 47,
  "page": 1,
  "size": 50,
  "filter_hash": "a3f5b2c1d4e6f789..."
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active.

403 Forbidden

Cause: The API key’s user is not a member of the organization (LOGGED_USER_NOT_MEMBER), or its role is limited to other facilities (FACILITY_NOT_IN_ROLE_SCOPE).

404 Not Found

Cause: The facility does not exist or is outside your organization’s perimeter (both answer the same)

{
  "detail": "Facility with id='660e8400-e29b-41d4-a716-446655440000' not found",
  "code": "NOT_FOUND"
}

Solution: Verify the facility_id with the Facilities API.

422 Validation Error

Cause: Missing required facility_id or invalid query parameter values

{
  "detail": [
    {
      "loc": ["query", "facility_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Solution: Ensure facility_id is provided and all filter values are valid.

Create Wastes (v2)

Create up to 5,000 wastes in one request

Update Waste

Modify an existing waste record

Bulk Delete by Filters

Delete all records matching the current filters

Facilities

List facilities for your organization

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

Create Wastes (v2)

Update Waste

Bulk Delete by Filters

Facilities

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints