> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Emissions Summary

> Get aggregated CO2e emissions grouped by scope, category, or month

# 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.

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID. Use `include_children=true` to also aggregate emissions from subsidiaries.

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Query Parameters

<ParamField query="start_date" type="string" required>
  Start date in ISO format (YYYY-MM-DD)

  **Example:** `2025-01-01`
</ParamField>

<ParamField query="end_date" type="string" required>
  End date in ISO format (YYYY-MM-DD). Maximum range: 2 years (730 days).

  **Example:** `2025-12-31`
</ParamField>

<ParamField query="group_by" type="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
</ParamField>

<ParamField query="include_children" type="boolean" default="false">
  Whether to include emissions from child organizations (subsidiaries). When `false`, only the specified organization's emissions are returned.
</ParamField>

## Response

<ResponseField name="organization_id" type="string">
  The organization UUID
</ResponseField>

<ResponseField name="start_date" type="date">
  Start date of the queried period
</ResponseField>

<ResponseField name="end_date" type="date">
  End date of the queried period
</ResponseField>

<ResponseField name="unit" type="string">
  Unit of measurement — always `tCO2e`
</ResponseField>

<ResponseField name="total_co2e" type="number">
  Total CO2e emissions in tonnes across all items
</ResponseField>

<ResponseField name="items" type="array">
  Array of emission breakdown items. Shape depends on `group_by`:

  <Expandable title="group_by=scope">
    <ResponseField name="scope" type="integer">
      GHG Protocol scope (1, 2, or 3)
    </ResponseField>

    <ResponseField name="co2e" type="number">
      CO2e emissions in tonnes for this scope
    </ResponseField>
  </Expandable>

  <Expandable title="group_by=category">
    <ResponseField name="scope" type="integer">
      GHG Protocol scope (1, 2, or 3)
    </ResponseField>

    <ResponseField name="category" type="string">
      Emission category name (e.g., `vehicles`, `electricity`, `purchases`)
    </ResponseField>

    <ResponseField name="co2e" type="number">
      CO2e emissions in tonnes for this scope+category
    </ResponseField>
  </Expandable>

  <Expandable title="group_by=month">
    <ResponseField name="year" type="integer">
      Calendar year
    </ResponseField>

    <ResponseField name="month" type="integer">
      Calendar month (1-12)
    </ResponseField>

    <ResponseField name="co2e" type="number">
      CO2e emissions in tonnes for this month
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### By Scope (default)

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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`));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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`)
  );
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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`)
  );
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Date range exceeds maximum of 730 days"}
```

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"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`)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "start_date"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Organization Tree" icon="sitemap" href="/api-reference/organizations/tree">
    View your organization hierarchy
  </Card>

  <Card title="Invoices" icon="file-invoice" href="/api-reference/invoices/overview">
    Manage energy invoices (Scope 2)
  </Card>

  <Card title="Vehicles" icon="truck" href="/api-reference/vehicles/overview">
    Manage vehicles (Scope 1)
  </Card>

  <Card title="Purchases" icon="cart-shopping" href="/api-reference/purchases/overview">
    Manage purchased goods (Scope 3)
  </Card>
</CardGroup>