> ## 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 Organization Emission Data

> Get all custom emission groups with their emission factors for an organization

<Warning>
  **Legacy API.** This page documents the previous version of the API. This particular
  operation has no documented equivalent in the current API yet, so this remains the
  documented way to do it. Prefer the current API for everything it already covers.
</Warning>

Retrieve all custom emission groups for an organization with all their emission factors included. This endpoint provides complete emission data in a single request.

<Note>
  This is the most comprehensive endpoint for custom emission data, returning groups with all their factors. Use this for data exports or complete inventory views.
</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

  **Example:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
</ParamField>

<ParamField header="x-user-id" type="string" required>
  Your user UUID

  **Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

### Path Parameters

<ParamField path="organization_id" type="string" required>
  UUID of the organization

  **Example:** `"org-uuid-here"`
</ParamField>

## Response

Returns paginated groups with all their emission factors included.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "page": 1,
  "size": 50,
  "total": 2,
  "items": [
    {
      "group_name": "Supplier ABC Materials 2024",
      "group_id": "group-uuid-1",
      "category": "purchases",
      "description": "EPD-verified emission factors",
      "group_start_date": "2024-01-01",
      "group_end_date": "2024-12-31",
      "ghg_type": 1,
      "group_uploaded_by": "procurement@company.com",
      "emission_factors": [
        {
          "ef_name": "Recycled Aluminum - Supplier ABC",
          "factor_id": "factor-uuid-1",
          "tag": "advanced",
          "factor_start_date": "2024-01-01",
          "factor_end_date": "2024-12-31",
          "factor_uploaded_by": "sustainability@company.com",
          "unit_id": "kg-unit-uuid",
          "unit": {
            "id": "kg-unit-uuid",
            "name": "kilogram",
            "abbreviation": "kg",
            "type": "mass"
          },
          "additional_docs": "EPD No. ABC-2024-001",
          "emission_factor_values": [
            {
              "gas_type": "CO2",
              "value": 2.15
            },
            {
              "gas_type": "CH4",
              "value": 0.008
            },
            {
              "gas_type": "N2O",
              "value": 0.002
            }
          ]
        }
      ]
    }
  ]
}
```

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/${DCYCLE_ORG_ID}" \
    -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
    -H "x-user-id: ${DCYCLE_USER_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  headers = {
      "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
      "x-user-id": os.getenv("DCYCLE_USER_ID")
  }

  org_id = os.getenv("DCYCLE_ORG_ID")

  response = requests.get(
      f"https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/{org_id}",
      headers=headers
  )

  data = response.json()
  print(f"Total groups: {data['total']}\n")

  for group in data['items']:
      print(f"Group: {group['group_name']} ({group['category']})")
      print(f"  Factors: {len(group['emission_factors'])}")

      for factor in group['emission_factors']:
          co2_value = next((v['value'] for v in factor['emission_factor_values'] if v['gas_type'] == 'CO2'), 0)
          print(f"    - {factor['ef_name']}: {co2_value} kg CO2/{factor['unit']['abbreviation']}")

      print()
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    'Authorization': `Bearer ${process.env.DCYCLE_API_KEY}`,
    'x-user-id': process.env.DCYCLE_USER_ID
  };

  const orgId = process.env.DCYCLE_ORG_ID;

  axios.get(
    `https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/${orgId}`,
    { headers }
  )
  .then(response => {
    const data = response.data;
    console.log(`Total groups: ${data.total}\n`);

    data.items.forEach(group => {
      console.log(`Group: ${group.group_name} (${group.category})`);
      console.log(`  Factors: ${group.emission_factors.length}`);

      group.emission_factors.forEach(factor => {
        const co2Value = factor.emission_factor_values.find(v => v.gas_type === 'CO2')?.value || 0;
        console.log(`    - ${factor.ef_name}: ${co2Value} kg CO2/${factor.unit.abbreviation}`);
      });

      console.log();
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

## Use Cases

### Complete Data Export

Export all custom emission data for reporting:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
all_data = []
page = 1

while True:
    response = requests.get(
        f"https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/{org_id}",
        headers=headers,
        params={"page": page, "size": 50}
    ).json()

    all_data.extend(response['items'])

    if len(all_data) >= response['total']:
        break

    page += 1

print(f"Exported {len(all_data)} groups")

# Convert to CSV or JSON for external use
import json
with open('custom_emission_data.json', 'w') as f:
    json.dump(all_data, f, indent=2)
```

### Inventory Analysis

Analyze all custom emission factors:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
data = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/{org_id}",
    headers=headers,
    params={"page": 1, "size": 100}
).json()

total_factors = 0
by_category = {"purchases": 0, "wastes": 0, "energy": 0}
by_tag = {"simple": 0, "advanced": 0}

for group in data['items']:
    category = group['category']
    by_category[category] += len(group['emission_factors'])
    total_factors += len(group['emission_factors'])

    for factor in group['emission_factors']:
        by_tag[factor['tag']] += 1

print(f"Custom Emission Factor Inventory:")
print(f"  Total factors: {total_factors}")
print(f"  By category:")
for cat, count in by_category.items():
    print(f"    {cat}: {count}")
print(f"  By complexity:")
for tag, count in by_tag.items():
    print(f"    {tag}: {count}")
```

### Build Factor Selector

Create a comprehensive factor selection UI:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function buildFactorSelector() {
  const data = await axios.get(
    `https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/${orgId}`,
    { headers }
  ).then(res => res.data);

  const factorsByCategory = {};

  data.items.forEach(group => {
    if (!factorsByCategory[group.category]) {
      factorsByCategory[group.category] = [];
    }

    group.emission_factors.forEach(factor => {
      factorsByCategory[group.category].push({
        value: factor.factor_id,
        label: `${factor.ef_name} (${factor.unit.abbreviation})`,
        group: group.group_name,
        uncertainty: factor.uncertainty_grade
      });
    });
  });

  return factorsByCategory;
}

// Usage
const factors = await buildFactorSelector();
// { purchases: [...], wastes: [...], energy: [...] }
```

### Data Quality Report

Generate quality metrics for custom factors:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
data = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/organization_emission_data/{org_id}",
    headers=headers,
    params={"page": 1, "size": 100}
).json()

high_uncertainty = []
missing_docs = []
expired = []

from datetime import date
today = date.today()

for group in data['items']:
    for factor in group['emission_factors']:
        # Check uncertainty
        if factor.get('uncertainty_grade', 0) > 50:
            high_uncertainty.append(factor['ef_name'])

        # Check documentation
        if not factor.get('additional_docs'):
            missing_docs.append(factor['ef_name'])

        # Check expiration
        if factor.get('factor_end_date'):
            end_date = date.fromisoformat(factor['factor_end_date'])
            if end_date < today:
                expired.append(factor['ef_name'])

print(f"Data Quality Report:")
print(f"  High uncertainty (>50%): {len(high_uncertainty)}")
print(f"  Missing documentation: {len(missing_docs)}")
print(f"  Expired factors: {len(expired)}")
```

## Response Fields

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="size" type="integer">
  Items per page
</ResponseField>

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

<ResponseField name="items" type="array">
  Array of custom emission group objects with their factors

  Each group contains:

  * `group_name`: Name of the group
  * `group_id`: UUID of the group
  * `category`: Category type
  * `description`: Group description
  * `group_start_date`: Optional validity start
  * `group_end_date`: Optional validity end
  * `ghg_type`: GHG origin type (1=fossil, 2=biogenic, 3=mixed)
  * `group_uploaded_by`: Optional uploader reference
  * `emission_factors`: Array of emission factor objects (with full details including unit info and gas values)
</ResponseField>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Groups" icon="list" href="/api-docs/custom-emission-groups/list">
    View groups only (no factors)
  </Card>

  <Card title="List by Category" icon="filter" href="/api-docs/custom-emission-groups/list-by-category">
    Filter by category
  </Card>

  <Card title="Get Group" icon="magnifying-glass" href="/api-docs/custom-emission-groups/get">
    View single group
  </Card>

  <Card title="List Factors" icon="chart-line" href="/api-docs/custom-emission-factors/list">
    List factors in a group
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.