Get Emissions Summary

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

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

import requests

url = "https://api.dcycle.io/v1/total-impacts"

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

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

print(response.text)

{
  "organization_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "unit": "<string>",
  "total_co2e": 123,
  "items": [
    {
      "scope": 123,
      "co2e": 123,
      "category": "<string>",
      "year": 123,
      "month": 123
    }
  ]
}

GET

total-impacts

Get Emissions Summary

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

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

import requests

url = "https://api.dcycle.io/v1/total-impacts"

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

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

print(response.text)

{
  "organization_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "unit": "<string>",
  "total_co2e": 123,
  "items": [
    {
      "scope": 123,
      "co2e": 123,
      "category": "<string>",
      "year": 123,
      "month": 123
    }
  ]
}

Get Emissions Summary

Retrieve aggregated CO2e emissions for your organization over a date range. Use the group_by parameter to control how results are broken down.

New API: This endpoint is part of the new API architecture with improved design and maintainability.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUID. Use include_children=true to also aggregate emissions from subsidiaries.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

string

required

Start date in ISO format (YYYY-MM-DD)Example: 2025-01-01

string

required

End date in ISO format (YYYY-MM-DD). Maximum range: 2 years (730 days).Example: 2025-12-31

string

default:"scope"

How to group the results. One of: scope, category, month.

scope — Aggregate by GHG Protocol scope (1, 2, 3)
category — Aggregate by emission category within each scope
month — Aggregate by calendar month

boolean

default:"false"

Whether to include emissions from child organizations (subsidiaries). When false, only the specified organization’s emissions are returned.

Response

string

The organization UUID

date

Start date of the queried period

date

End date of the queried period

string

Unit of measurement — always tCO2e

number

Total CO2e emissions in tonnes across all items

array

Array of emission breakdown items. Shape depends on group_by:

Show group_by=scope

integer

GHG Protocol scope (1, 2, or 3)

number

CO2e emissions in tonnes for this scope

Show group_by=category

integer

GHG Protocol scope (1, 2, or 3)

string

Emission category name (e.g., vehicles, electricity, purchases)

number

CO2e emissions in tonnes for this scope+category

Show group_by=month

integer

Calendar year

integer

Calendar month (1-12)

number

CO2e emissions in tonnes for this month

Example

By Scope (default)

curl -X GET "https://api.dcycle.io/v1/total-impacts?start_date=2025-01-01&end_date=2025-12-31&group_by=scope" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID")
}

response = requests.get(
    "https://api.dcycle.io/v1/total-impacts",
    headers=headers,
    params={
        "start_date": "2025-01-01",
        "end_date": "2025-12-31",
        "group_by": "scope"
    }
)

data = response.json()
print(f"Total: {data['total_co2e']} tCO2e")
for item in data["items"]:
    print(f"  Scope {item['scope']}: {item['co2e']} tCO2e")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID
};

const response = await axios.get(
  'https://api.dcycle.io/v1/total-impacts',
  {
    headers,
    params: {
      start_date: '2025-01-01',
      end_date: '2025-12-31',
      group_by: 'scope'
    }
  }
);

const { total_co2e, items } = response.data;
console.log(`Total: ${total_co2e} tCO2e`);
items.forEach(item => console.log(`  Scope ${item.scope}: ${item.co2e} tCO2e`));

Successful Response

{
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "unit": "tCO2e",
  "total_co2e": 1550.8,
  "items": [
    { "scope": 1, "co2e": 150.5 },
    { "scope": 2, "co2e": 200.3 },
    { "scope": 3, "co2e": 1200.0 }
  ]
}

By Category

curl -X GET "https://api.dcycle.io/v1/total-impacts?start_date=2025-01-01&end_date=2025-12-31&group_by=category" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

response = requests.get(
    "https://api.dcycle.io/v1/total-impacts",
    headers=headers,
    params={
        "start_date": "2025-01-01",
        "end_date": "2025-12-31",
        "group_by": "category",
    },
)

for item in response.json()["items"]:
    print(f"  Scope {item['scope']} / {item['category']}: {item['co2e']} tCO2e")

const catResponse = await axios.get(
  'https://api.dcycle.io/v1/total-impacts',
  {
    headers,
    params: {
      start_date: '2025-01-01',
      end_date: '2025-12-31',
      group_by: 'category',
    },
  }
);

catResponse.data.items.forEach(item =>
  console.log(`  Scope ${item.scope} / ${item.category}: ${item.co2e} tCO2e`)
);

Successful Response

{
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "unit": "tCO2e",
  "total_co2e": 1550.8,
  "items": [
    { "scope": 1, "category": "vehicles", "co2e": 100.0 },
    { "scope": 1, "category": "combustion", "co2e": 50.5 },
    { "scope": 2, "category": "electricity", "co2e": 200.3 },
    { "scope": 3, "category": "purchases", "co2e": 800.0 },
    { "scope": 3, "category": "travels", "co2e": 150.0 },
    { "scope": 3, "category": "goods_shipped", "co2e": 250.0 }
  ]
}

By Month

curl -X GET "https://api.dcycle.io/v1/total-impacts?start_date=2025-01-01&end_date=2025-12-31&group_by=month" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

response = requests.get(
    "https://api.dcycle.io/v1/total-impacts",
    headers=headers,
    params={
        "start_date": "2025-01-01",
        "end_date": "2025-12-31",
        "group_by": "month",
    },
)

for item in response.json()["items"]:
    print(f"  {item['year']}-{item['month']:02d}: {item['co2e']} tCO2e")

const monthResponse = await axios.get(
  'https://api.dcycle.io/v1/total-impacts',
  {
    headers,
    params: {
      start_date: '2025-01-01',
      end_date: '2025-12-31',
      group_by: 'month',
    },
  }
);

monthResponse.data.items.forEach(item =>
  console.log(`  ${item.year}-${String(item.month).padStart(2, '0')}: ${item.co2e} tCO2e`)
);

Successful Response

{
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "unit": "tCO2e",
  "total_co2e": 1550.8,
  "items": [
    { "year": 2025, "month": 1, "co2e": 120.5 },
    { "year": 2025, "month": 2, "co2e": 135.2 },
    { "year": 2025, "month": 3, "co2e": 142.1 }
  ]
}

Common Errors

400 Bad Request

Cause: start_date is after end_date, or date range exceeds 2 years (730 days)

{"detail": "Date range exceeds maximum of 730 days"}

401 Unauthorized

Cause: Missing or invalid API key

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

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

422 Unprocessable Entity

Cause: Missing required query parameters (start_date or end_date)

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

Organization Tree

View your organization hierarchy

Invoices

Manage energy invoices (Scope 2)

Vehicles

Manage vehicles (Scope 1)

Purchases

Manage purchased goods (Scope 3)

​Get Emissions Summary

​Request

​Headers

​Query Parameters

​Response

​Example

​By Scope (default)

​Successful Response

​By Category

​Successful Response

​By Month

​Successful Response

​Common Errors

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

Organization Tree

Invoices

Vehicles

Purchases

Get Emissions Summary

Request

Headers

Query Parameters

Response

Example

By Scope (default)

Successful Response

By Category

Successful Response

By Month

Successful Response

Common Errors

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints