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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUID. Use include_children=true to also aggregate emissions from subsidiaries.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Query Parameters

​
start_date
string
required
Start date in ISO format (YYYY-MM-DD)Example: 2025-01-01
​
end_date
string
required
End date in ISO format (YYYY-MM-DD). Maximum range: 2 years (730 days).Example: 2025-12-31
​
group_by
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
​
include_children
boolean
default:"false"
Whether to include emissions from child organizations (subsidiaries). When false, only the specified organization’s emissions are returned.

​
Response

​
organization_id
string
The organization UUID
​
start_date
string
Start date of the queried period
​
end_date
string
End date of the queried period
​
unit
string
Unit of measurement — always tCO2e
​
total_co2e
number
Total CO2e emissions in tonnes across all items
​
items
array
Array of emission breakdown items. Shape depends on group_by:

​
Examples

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

​
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

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

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

​
Error Responses

StatusDescription
400start_date is after end_date, or date range exceeds 2 years
401Missing or invalid API key
422Missing required query parameters

Organization Tree

View your organization hierarchy

Invoices

Manage energy invoices (Scope 2)

Vehicles

Manage vehicles (Scope 1)

Purchases

Manage purchased goods (Scope 3)