> ## 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 Custom Emission Groups

> Get paginated list of custom emission groups for your organization

# List Custom Emission Groups

Retrieve all custom emission groups for your organization with pagination support. This endpoint returns groups without their associated emission factors.

<Note>
  To get groups with their emission factors included, use the [Organization Data](/api-docs/custom-emission-groups/organization-data) endpoint instead.
</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>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number
</ParamField>

<ParamField query="size" type="integer" default="50">
  Items per page (max: 100)
</ParamField>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "page": 1,
  "size": 50,
  "total": 3,
  "items": [
    {
      "id": "group-uuid-1",
      "name": "Supplier ABC Materials 2024",
      "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"
    },
    {
      "id": "group-uuid-2",
      "name": "Wind Farm PPA 2024-2034",
      "category": "energy",
      "description": "10-year renewable energy PPA",
      "group_start_date": "2024-01-01",
      "group_end_date": "2034-12-31",
      "ghg_type": 2,
      "group_uploaded_by": "energy_manager@company.com"
    },
    {
      "id": "group-uuid-3",
      "name": "Regional Waste Facility",
      "category": "wastes",
      "description": "Custom waste treatment factors",
      "group_start_date": null,
      "group_end_date": null,
      "ghg_type": 3,
      "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?page=1&size=50" \
    -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -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-organization-id": os.getenv("DCYCLE_ORG_ID"),
      "x-user-id": os.getenv("DCYCLE_USER_ID")
  }

  response = requests.get(
      "https://api.dcycle.io/api/v1/custom_emission_groups",
      headers=headers,
      params={"page": 1, "size": 50}
  )

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

  for group in data['items']:
      print(f"- {group['name']} ({group['category']})")
  ```

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

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

  axios.get(
    'https://api.dcycle.io/api/v1/custom_emission_groups',
    {
      headers,
      params: { page: 1, size: 50 }
    }
  )
  .then(response => {
    const data = response.data;
    console.log(`Total groups: ${data.total}`);

    data.items.forEach(group => {
      console.log(`- ${group.name} (${group.category})`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

## Use Cases

### List All Groups

Get overview of all custom emission groups:

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

print(f"Found {groups['total']} custom emission groups:\n")

for group in groups['items']:
    ghg_type_name = {1: 'Fossil', 2: 'Biogenic', 3: 'Mixed'}[group['ghg_type']]
    print(f"[{group['category'].upper()}] {group['name']}")
    print(f"  GHG Type: {ghg_type_name}")
    print(f"  ID: {group['id']}\n")
```

### Filter by Category

List only groups of a specific category:

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

# Filter for purchases only
purchase_groups = [g for g in all_groups['items'] if g['category'] == 'purchases']

print(f"Purchase groups: {len(purchase_groups)}")
for group in purchase_groups:
    print(f"- {group['name']}")
```

<Note>
  For server-side category filtering, use the [List by Category](/api-docs/custom-emission-groups/list-by-category) endpoint instead.
</Note>

### Display in UI

Create a dropdown selector for groups:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function loadGroupSelector(category) {
  const response = await axios.get(
    'https://api.dcycle.io/api/v1/custom_emission_groups',
    {
      headers,
      params: { page: 1, size: 100 }
    }
  );

  const groups = response.data.items
    .filter(g => g.category === category)
    .map(g => ({
      value: g.id,
      label: g.name,
      description: g.description
    }));

  return groups;
}

// Usage
const purchaseGroups = await loadGroupSelector('purchases');
```

### Pagination Example

Handle large numbers of groups:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_all_groups(headers):
    all_groups = []
    page = 1

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

        all_groups.extend(response['items'])

        # Check if we've retrieved all groups
        if len(all_groups) >= response['total']:
            break

        page += 1

    return all_groups

groups = get_all_groups(headers)
print(f"Retrieved {len(groups)} groups across all pages")
```

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the group
</ResponseField>

<ResponseField name="name" type="string">
  Group name
</ResponseField>

<ResponseField name="category" type="string">
  Category type: `purchases`, `wastes`, or `energy`
</ResponseField>

<ResponseField name="description" type="string">
  Detailed description of the group
</ResponseField>

<ResponseField name="ghg_type" type="integer">
  GHG origin type: `1` (fossil), `2` (biogenic), or `3` (mixed)
</ResponseField>

<ResponseField name="group_start_date" type="date">
  Optional validity start date
</ResponseField>

<ResponseField name="group_end_date" type="date">
  Optional validity end date
</ResponseField>

<ResponseField name="group_uploaded_by" type="string">
  Optional reference to who created the group
</ResponseField>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Group" icon="magnifying-glass" href="/api-docs/custom-emission-groups/get">
    View group with factors
  </Card>

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