> ## 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 Groups by Category

> Get custom emission groups filtered by category 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 a specific organization filtered by category (purchases, wastes, or energy).

<Note>
  This endpoint requires the `organization_id` in the path rather than using the header. Ensure you use the correct organization ID.
</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>

<ParamField path="category" type="string" required>
  Category to filter by

  **Values:** `"purchases"`, `"wastes"`, or `"energy"`
</ParamField>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "organization_id": "org-uuid",
  "emission_groups": [
    {
      "id": "group-uuid-1",
      "name": "Supplier ABC Materials 2024",
      "category": "purchases",
      "group_start_date": "2024-01-01",
      "group_end_date": "2024-12-31",
      "group_uploaded_by": "procurement@company.com"
    },
    {
      "id": "group-uuid-2",
      "name": "Supplier XYZ Products",
      "category": "purchases",
      "group_start_date": null,
      "group_end_date": null,
      "group_uploaded_by": null
    }
  ]
}
```

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/${DCYCLE_ORG_ID}/purchases" \
    -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")
  category = "purchases"

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

  data = response.json()
  print(f"Found {len(data['emission_groups'])} {category} groups:\n")

  for group in data['emission_groups']:
      print(f"- {group['name']} (ID: {group['id']})")
  ```

  ```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;
  const category = 'purchases';

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

    data.emission_groups.forEach(group => {
      console.log(`- ${group.name} (ID: ${group.id})`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

## Use Cases

### Load Category-Specific Groups

Get groups for a specific category when creating records:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# When creating a purchase, load purchase groups
category = "purchases"
groups = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
    headers=headers
).json()

print(f"Available purchase groups:")
for group in groups['emission_groups']:
    print(f"  [{group['id']}] {group['name']}")
```

### Build Category Selector

Create a dropdown for each category:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function loadGroupsByCategory(category) {
  const orgId = process.env.DCYCLE_ORG_ID;

  const response = await axios.get(
    `https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/${orgId}/${category}`,
    { headers }
  );

  return response.data.emission_groups.map(group => ({
    value: group.id,
    label: group.name
  }));
}

// Usage in UI
const purchaseGroups = await loadGroupsByCategory('purchases');
const wasteGroups = await loadGroupsByCategory('wastes');
const energyGroups = await loadGroupsByCategory('energy');
```

### Filter All Categories

Get groups for all categories:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
categories = ["purchases", "wastes", "energy"]
all_groups = {}

for category in categories:
    response = requests.get(
        f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
        headers=headers
    ).json()

    all_groups[category] = response['emission_groups']

# Display summary
for category, groups in all_groups.items():
    print(f"{category.capitalize()}: {len(groups)} groups")
```

### Check Group Availability

Verify groups exist before allowing custom factor selection:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
category = "energy"
groups = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
    headers=headers
).json()

if len(groups['emission_groups']) == 0:
    print(f"⚠️ No {category} groups available. Create one first.")
else:
    print(f"✅ {len(groups['emission_groups'])} {category} groups available")
```

## Response Fields

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

<ResponseField name="emission_groups" type="array">
  Array of custom emission group objects

  Each group contains:

  * `id`: Group UUID
  * `name`: Group name
  * `category`: Category type
  * `group_start_date`: Optional validity start date
  * `group_end_date`: Optional validity end date
  * `group_uploaded_by`: Optional uploader reference
</ResponseField>

## Common Errors

### 422 Validation Error - Invalid Category

**Cause:** Invalid category. Must be 'purchases', 'wastes', or 'energy'

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid category. Must be 'purchases', 'wastes', or 'energy'",
  "code": "VALIDATION_ERROR"
}
```

**Solution:** Use `purchases`, `wastes`, or `energy` for the category parameter.

### 404 Not Found

**Cause:** Organization not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Organization not found",
  "code": "NOT_FOUND"
}
```

**Solution:** Verify the organization ID is correct.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List All Groups" icon="list" href="/api-docs/custom-emission-groups/list">
    View groups across all categories
  </Card>

  <Card title="Organization Data" icon="building" href="/api-docs/custom-emission-groups/organization-data">
    Get groups with factors
  </Card>

  <Card title="Create Group" icon="plus" href="/api-docs/custom-emission-groups/create">
    Add new group
  </Card>
</CardGroup>


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