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

# List Historical Emissions

> Get all historical emission entries for your organization

# List Historical Emissions

Retrieve all historical emission entries for your organization, including the calculated CO2e from total impacts when available.

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

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

## Response

<ResponseField name="items" type="array[object]">
  List of historical emission entries

  <Expandable title="Historical Emission Object">
    <ResponseField name="id" type="string">UUID of the entry</ResponseField>
    <ResponseField name="organization_id" type="string">Organization UUID</ResponseField>
    <ResponseField name="start_date" type="date">Start date (ISO 8601)</ResponseField>
    <ResponseField name="end_date" type="date">End date (ISO 8601)</ResponseField>
    <ResponseField name="scope" type="integer">GHG scope (1, 2, or 3) — derived from category</ResponseField>
    <ResponseField name="category" type="string">Emission category (e.g. `electricity`, `transport`)</ResponseField>
    <ResponseField name="total_co2e" type="number">Total CO2e in kilograms</ResponseField>
    <ResponseField name="description" type="string | null">Free text description</ResponseField>
    <ResponseField name="ghg_gas" type="string">GHG gas type</ResponseField>
    <ResponseField name="ghg_type" type="integer">0 = fossil, 1 = biomass</ResponseField>
    <ResponseField name="enabled" type="boolean">Whether this entry is enabled</ResponseField>
    <ResponseField name="co2e" type="number | null">Calculated CO2e from total impacts (null if not yet calculated)</ResponseField>
    <ResponseField name="file_id" type="string | null">UUID of attached evidence file</ResponseField>
    <ResponseField name="created_at" type="datetime">Creation timestamp</ResponseField>
    <ResponseField name="updated_at" type="string | null">Last update timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of entries
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/historical-emissions" \
    -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/historical-emissions",
      headers=headers,
  )

  data = response.json()
  print(f"Total entries: {data['total']}")
  for item in data["items"]:
      print(f"  [{item['category']}] {item['start_date']} → {item['end_date']}: {item['total_co2e']} kg CO2e")
  ```

  ```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,
  };

  axios.get('https://api.dcycle.io/v1/historical-emissions', { headers })
    .then(response => {
      const { items, total } = response.data;
      console.log(`Total: ${total}`);
      items.forEach(i => console.log(`  [${i.category}] ${i.total_co2e} kg CO2e`));
    });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "start_date": "2022-01-01",
      "end_date": "2022-12-31",
      "scope": 2,
      "category": "electricity",
      "total_co2e": 45200.5,
      "description": "2022 electricity consumption from utility bills",
      "ghg_gas": "co2e",
      "ghg_type": 0,
      "enabled": true,
      "co2e": 45200.5,
      "file_id": null,
      "file_url": null,
      "file_name": null,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": null
    }
  ],
  "total": 1
}
```

## Common Errors

### 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"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create" icon="plus" href="/api-reference/historical-emissions/create">
    Add a new historical emission entry
  </Card>

  <Card title="Emissions Summary" icon="chart-pie" href="/api-reference/emissions/get-summary">
    View calculated emissions across all sources
  </Card>
</CardGroup>