Skip to main content
GET
/
api
/
v1
/
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));
{
  "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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
​
x-user-id
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Query Parameters

​
page
integer
default:"1"
Page number
​
size
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}"

​
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

​
id
string
Unique identifier for the group
​
name
string
Group name
​
category
string
Category type: purchases, wastes, or energy
​
description
string
Detailed description of the group
​
ghg_type
integer
GHG origin type: 1 (fossil), 2 (biogenic), or 3 (mixed)
​
group_start_date
date
Optional validity start date
​
group_end_date
date
Optional validity end date
​
group_uploaded_by
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