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

# Get Organization Emission Data

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>