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

# Calculation Steps

> View the detailed CO2e conversion steps for a commuting period

# Calculation Steps

Retrieve the full CO2e conversion breakdown for a commuting period. Each step shows the raw value, conversion factor applied, calculated result, and the emission factor source — useful for auditing and understanding how commuting emissions are computed.

Steps are grouped by year period (since a commuting period can span multiple years) and split into:

* **common\_steps** — activity/unit normalization (e.g. `person × km → pkm`)
* **details** — emission factor application, broken down by greenhouse gas (CO2, CH4, N2O)

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

### Path Parameters

<ParamField path="employee_historic_id" type="string" required>
  The commuting period UUID

  **Example:** `660e8400-e29b-41d4-a716-446655440000`
</ParamField>

## Response

Returns the calculation breakdown (HTTP 200).

<ResponseField name="total_co2e" type="number">
  Total CO2e emissions in kg for the entire commuting period.
</ResponseField>

<ResponseField name="periods" type="array[object]">
  Calculation steps grouped by year period.

  <Expandable title="Period Object">
    <ResponseField name="start_date" type="date">Period start date.</ResponseField>
    <ResponseField name="end_date" type="date">Period end date.</ResponseField>
    <ResponseField name="co2e" type="number">CO2e emissions in kg for this period.</ResponseField>

    <ResponseField name="common_steps" type="array[object]">
      Activity/unit normalization steps applied before emission factors.

      <Expandable title="Step Object">
        <ResponseField name="step" type="integer">Step number in the conversion chain.</ResponseField>

        <ResponseField name="raw_value" type="object">
          Input value and unit for this step.

          <Expandable title="Value Object">
            <ResponseField name="value" type="number">Numeric value.</ResponseField>

            <ResponseField name="unit" type="object">
              <Expandable title="Unit Object">
                <ResponseField name="unit_id" type="string">Unit identifier.</ResponseField>
                <ResponseField name="unit_name" type="string">Human-readable unit name.</ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="conversion_factor" type="object">
          Factor applied at this step.

          <Expandable title="Conversion Factor">
            <ResponseField name="value" type="number">Factor value.</ResponseField>
            <ResponseField name="type" type="string">Operator type (e.g. `multiply`, `divide`).</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="calculated_value" type="object">
          Result after applying the conversion factor (same structure as `raw_value`).
        </ResponseField>

        <ResponseField name="source" type="object">
          Emission factor source reference.

          <Expandable title="Source Object">
            <ResponseField name="source_id" type="string">Source database identifier.</ResponseField>
            <ResponseField name="source_name" type="string">Source name (e.g. `DEFRA`, `GHG Protocol`).</ResponseField>
            <ResponseField name="source_version" type="string">Source version.</ResponseField>
            <ResponseField name="source_reference_year" type="integer | null">Reference year for the factor.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="coincidence" type="string | null">Matched concept description.</ResponseField>
        <ResponseField name="coincidence_concept_id" type="string | null">Matched concept UUID.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="details" type="object">
      Emission factor steps broken down by greenhouse gas.

      <Expandable title="Details Object">
        <ResponseField name="co2e_from_co2" type="array[object]">Steps for CO2 component (same structure as common\_steps).</ResponseField>
        <ResponseField name="co2e_from_ch4" type="array[object]">Steps for CH4 component.</ResponseField>
        <ResponseField name="co2e_from_n2o" type="array[object]">Steps for N2O component.</ResponseField>
        <ResponseField name="co2e" type="array[object]">Steps for combined CO2e (when not broken down by gas).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/employee-historic/660e8400-e29b-41d4-a716-446655440000/steps" \
    -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

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")

  response = requests.get(
      "https://api.dcycle.io/v1/employee-historic/660e8400-e29b-41d4-a716-446655440000/steps",
      headers={
          "x-api-key": api_key,
          "x-organization-id": org_id
      }
  )

  data = response.json()
  print(f"Total CO2e: {data['total_co2e']:.2f} kg")
  for period in data["periods"]:
      print(f"\n  Period {period['start_date']} → {period['end_date']}: {period['co2e']:.2f} kg")
      for step in period["common_steps"]:
          raw = step["raw_value"]
          calc = step["calculated_value"]
          factor = step["conversion_factor"]
          print(f"    Step {step['step']}: {raw['value']} {raw['unit']['unit_name']} "
                f"× {factor['value']} = {calc['value']} {calc['unit']['unit_name']}")
  ```

  ```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 periodId = '660e8400-e29b-41d4-a716-446655440000';

  axios.get(`https://api.dcycle.io/v1/employee-historic/${periodId}/steps`, { headers })
  .then(({ data }) => {
    console.log(`Total CO2e: ${data.total_co2e.toFixed(2)} kg`);
    data.periods.forEach(period => {
      console.log(`\n  Period ${period.start_date} → ${period.end_date}: ${period.co2e.toFixed(2)} kg`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total_co2e": 1245.5,
  "periods": [
    {
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "co2e": 1245.5,
      "common_steps": [
        {
          "step": 1,
          "raw_value": {
            "value": 1.0,
            "unit": { "unit_id": "person", "unit_name": "person" }
          },
          "conversion_factor": { "value": 15.0, "type": "multiply" },
          "calculated_value": {
            "value": 15.0,
            "unit": { "unit_id": "km", "unit_name": "km" }
          },
          "source": {
            "source_id": "user_input",
            "source_name": "User Input",
            "source_version": "1.0",
            "source_reference_year": null
          },
          "coincidence": null,
          "coincidence_concept_id": null
        }
      ],
      "details": {
        "co2e_from_co2": [
          {
            "step": 1,
            "raw_value": {
              "value": 3900.0,
              "unit": { "unit_id": "pkm", "unit_name": "pkm" }
            },
            "conversion_factor": { "value": 0.17148, "type": "multiply" },
            "calculated_value": {
              "value": 668.77,
              "unit": { "unit_id": "g_co2e", "unit_name": "g CO2" }
            },
            "source": {
              "source_id": "defra_2024",
              "source_name": "DEFRA",
              "source_version": "2024",
              "source_reference_year": 2024
            },
            "coincidence": "Cars (by size) - Medium car - Petrol",
            "coincidence_concept_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        ],
        "co2e_from_ch4": [],
        "co2e_from_n2o": [],
        "co2e": []
      }
    }
  ]
}
```

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

### 404 Not Found

**Cause:** Commuting period not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Employee Historic with id=UUID('...') not found", "code": "EMPLOYEE_HISTORIC_NOT_FOUND"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Commuting Periods" icon="route" href="/api-reference/employees/commuting-periods/list">
    List all commuting periods
  </Card>

  <Card title="Get Commuting Period" icon="magnifying-glass" href="/api-reference/employees/commuting-periods/get">
    Get a specific commuting period
  </Card>
</CardGroup>