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

# List Groups by Category

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>