List Custom Emission Groups

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

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

import requests

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

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

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

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/api/v1/custom_emission_groups \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>'

{
  "id": "<string>",
  "name": "<string>",
  "category": "<string>",
  "description": "<string>",
  "ghg_type": 123,
  "group_start_date": "<string>",
  "group_end_date": "<string>",
  "group_uploaded_by": "<string>"
}

GET

api

custom_emission_groups

List Custom Emission Groups

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

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

import requests

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

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

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

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/api/v1/custom_emission_groups \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>'

{
  "id": "<string>",
  "name": "<string>",
  "category": "<string>",
  "description": "<string>",
  "ghg_type": 123,
  "group_start_date": "<string>",
  "group_end_date": "<string>",
  "group_uploaded_by": "<string>"
}

List Custom Emission Groups

Retrieve all custom emission groups for your organization with pagination support. This endpoint returns groups without their associated emission factors.

To get groups with their emission factors included, use the Organization Data endpoint instead.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query Parameters

integer

default:"1"

Page number

integer

default:"50"

Items per page (max: 100)

Response

{
  "page": 1,
  "size": 50,
  "total": 3,
  "items": [
    {
      "id": "group-uuid-1",
      "name": "Supplier ABC Materials 2024",
      "category": "purchases",
      "description": "EPD-verified emission factors",
      "group_start_date": "2024-01-01",
      "group_end_date": "2024-12-31",
      "ghg_type": 1,
      "group_uploaded_by": "procurement@company.com"
    },
    {
      "id": "group-uuid-2",
      "name": "Wind Farm PPA 2024-2034",
      "category": "energy",
      "description": "10-year renewable energy PPA",
      "group_start_date": "2024-01-01",
      "group_end_date": "2034-12-31",
      "ghg_type": 2,
      "group_uploaded_by": "energy_manager@company.com"
    },
    {
      "id": "group-uuid-3",
      "name": "Regional Waste Facility",
      "category": "wastes",
      "description": "Custom waste treatment factors",
      "group_start_date": null,
      "group_end_date": null,
      "ghg_type": 3,
      "group_uploaded_by": null
    }
  ]
}

Example

curl "https://api.dcycle.io/api/v1/custom_emission_groups?page=1&size=50" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "x-user-id": os.getenv("DCYCLE_USER_ID")
}

response = requests.get(
    "https://api.dcycle.io/api/v1/custom_emission_groups",
    headers=headers,
    params={"page": 1, "size": 50}
)

data = response.json()
print(f"Total groups: {data['total']}")

for group in data['items']:
    print(f"- {group['name']} ({group['category']})")

const axios = require('axios');

const headers = {
  'Authorization': `Bearer ${process.env.DCYCLE_API_KEY}`,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'x-user-id': process.env.DCYCLE_USER_ID
};

axios.get(
  'https://api.dcycle.io/api/v1/custom_emission_groups',
  {
    headers,
    params: { page: 1, size: 50 }
  }
)
.then(response => {
  const data = response.data;
  console.log(`Total groups: ${data.total}`);

  data.items.forEach(group => {
    console.log(`- ${group.name} (${group.category})`);
  });
})
.catch(error => console.error(error));

Use Cases

List All Groups

Get overview of all custom emission groups:

groups = requests.get(
    "https://api.dcycle.io/api/v1/custom_emission_groups",
    headers=headers,
    params={"page": 1, "size": 100}
).json()

print(f"Found {groups['total']} custom emission groups:\n")

for group in groups['items']:
    ghg_type_name = {1: 'Fossil', 2: 'Biogenic', 3: 'Mixed'}[group['ghg_type']]
    print(f"[{group['category'].upper()}] {group['name']}")
    print(f"  GHG Type: {ghg_type_name}")
    print(f"  ID: {group['id']}\n")

Filter by Category

List only groups of a specific category:

all_groups = requests.get(
    "https://api.dcycle.io/api/v1/custom_emission_groups",
    headers=headers,
    params={"page": 1, "size": 100}
).json()

# Filter for purchases only
purchase_groups = [g for g in all_groups['items'] if g['category'] == 'purchases']

print(f"Purchase groups: {len(purchase_groups)}")
for group in purchase_groups:
    print(f"- {group['name']}")

For server-side category filtering, use the List by Category endpoint instead.

Display in UI

Create a dropdown selector for groups:

async function loadGroupSelector(category) {
  const response = await axios.get(
    'https://api.dcycle.io/api/v1/custom_emission_groups',
    {
      headers,
      params: { page: 1, size: 100 }
    }
  );

  const groups = response.data.items
    .filter(g => g.category === category)
    .map(g => ({
      value: g.id,
      label: g.name,
      description: g.description
    }));

  return groups;
}

// Usage
const purchaseGroups = await loadGroupSelector('purchases');

Pagination Example

Handle large numbers of groups:

def get_all_groups(headers):
    all_groups = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/api/v1/custom_emission_groups",
            headers=headers,
            params={"page": page, "size": 100}
        ).json()

        all_groups.extend(response['items'])

        # Check if we've retrieved all groups
        if len(all_groups) >= response['total']:
            break

        page += 1

    return all_groups

groups = get_all_groups(headers)
print(f"Retrieved {len(groups)} groups across all pages")

Response Fields

string

Unique identifier for the group

string

Group name

string

Category type: purchases, wastes, or energy

string

Detailed description of the group

integer

GHG origin type: 1 (fossil), 2 (biogenic), or 3 (mixed)

date

Optional validity start date

date

Optional validity end date

string

Optional reference to who created the group

Get Group

View group with factors

List by Category

Filter by category

Organization Data

Get groups with factors

Create Group

Add new group

Create Custom Emission Group Get Custom Emission Group

Introduction

Logistics

Facilities

Vehicles

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

List Custom Emission Groups

List Custom Emission Groups

Request

Headers

Query Parameters

Response

Example

Use Cases

List All Groups

Filter by Category

Display in UI

Response Fields

Get Group

List by Category

Organization Data

Create Group

​List Custom Emission Groups

​Request

​Headers

​Query Parameters

​Response

​Example

​Use Cases

​List All Groups

​Filter by Category

​Display in UI

​Pagination Example

​Response Fields

​Related Endpoints

Get Group

List by Category

Organization Data

Create Group

List Custom Emission Groups

Request

Headers

Query Parameters

Response

Example

Use Cases

List All Groups

Filter by Category

Display in UI

Pagination Example

Response Fields

Related Endpoints