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));

{
  "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": {}
  },
  "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));

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

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

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

Query Parameters

facility_id

string

required

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

status[]

array[string]

Filter by waste record status. Can be specified multiple times.Available values: uploaded, active, loading, errorExample: status[]=active&status[]=uploaded

start_date

date

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

end_date

date

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

file_id[]

array[string]

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

created_at_from

datetime

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

created_at_to

datetime

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

co2e_status

string

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

identification_name[]

array[string]

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

ler_code[]

array[string]

Filter by LER (European Waste Catalogue) code. Can be specified multiple times.Example: ler_code[]=15 01 01

rd_code[]

array[string]

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

project_id

string

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

sort

string

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

page

integer

default:"1"

Page number for paginationExample: 1

size

integer

default:"50"

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

Response

items

array[object]

Array of waste record objects

Show Waste Object

string

Unique identifier (UUID) for the waste record

type

string

Always "wastes"

identification_name

string

Waste identification name or invoice number

invoice_id

string

Alias for identification_name

description

string

Description of the waste

status

string

Processing status: uploaded, active, loading, or error

start_date

date

Start date of the waste period

end_date

date

End date of the waste period

facility_id

string | null

UUID of the facility this waste belongs to

base_quantity

number

Original waste quantity in the specified unit

quantity

number

Effective quantity after applying the facility percentage factor

percentage

number | null

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

total_km_to_waste_center

number

Distance to waste treatment center in kilometers

low_code

string | null

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

rd_code

string | null

RD disposal/recovery operation code from the linked emission factor

co2e

number | null

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

co2e_biomass

number

Biogenic CO2 emissions in kg CO2e

custom_emission_factor_id

string | null

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

custom_emission_factor

object | null

Full custom emission factor object if one is linked

unit

object | null

Unit of measurement for the waste quantity

Show Unit Object

string

Unit UUID

name

string

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

type

string

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

user

object | null

User who uploaded or created the record

Show User Object

string

User UUID

first_name

string

First name

last_name

string

Last name

string

Email address

prefix

string | null

Phone prefix

phone_number

string | null

Phone number

onboarding_done

boolean | null

Whether the user has completed onboarding

profile_img_url

string | null

Profile image URL

uploaded_by

string | null

UUID of the user who created the record

source_invoice_id

string

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

file_id

string | null

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

file_name

string | null

Name of the linked import file

file_url

string | null

Download URL for the linked import file

error_messages

array[string] | null

List of error messages if status is error

linked_projects

array[object]

Projects this waste record is linked to

facility_percentages

array[object]

Facility distribution breakdown when a record is split across multiple facilities

created_at

datetime

Timestamp when the record was created

total

integer

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

total2

integer

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

total_general

integer

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

page

integer

Current page number

size

integer

Number of items per page

filter_hash

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

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

Wastes API Create Waste

​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