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>",
    "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>"
}

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>",
    "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>"
}

List Wastes

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, errorExample: 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 Waste Catalogue) code. Can be specified multiple times.Example: ler_code[]=15 01 01

array[string]

Filter by RD disposal/recovery code. Can be specified multiple times.Example: rd_code[]=R1

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 number

string

Alias for identification_name

string

Description of the waste

string

Processing status: uploaded, active, loading, or error

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

LER (European Waste Catalogue) code from the linked emission factor

string | null

RD disposal/recovery operation code from the linked emission factor

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

Internal source record UUID (used when a single record is split across multiple facilities)

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.

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": "20 03 01",
      "rd_code": "D1",
      "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",
      "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 facility does not belong to your organization

{
  "detail": "Facility doesn't belong to organization",
  "code": "FACILITY_NOT_BELONG_TO_ORGANIZATION"
}

Solution: Verify the facility_id belongs to your organization using 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 Waste

Add a new waste disposal record

Update Waste

Modify an existing waste record

Bulk Delete by Filters

Delete all records matching the current filters

Facilities

List facilities for your organization

​List Wastes

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​Related Endpoints

Create Waste

Update Waste

Bulk Delete by Filters

Facilities

List Wastes

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Validation Error

Related Endpoints