> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Organization Asset Groups

> List all asset groups belonging to your organization with asset counts.

## Overview

List all asset groups belonging to your organization. Asset groups help you organize your assets by category, project, or purpose. Each group includes a count of assigned assets for easy inventory management.

## Quick Start

### Authentication

Include your API key in the `X-API-KEY` header:

```bash theme={null}
X-API-KEY: your_api_key_here
```

### Example Request

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      method: "GET",
      headers: {
        "X-API-KEY": "YOUR_API_KEY_HERE",
      },
    }
  );

  const data = await response.json();
  console.log(data.groups);
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      method: "GET",
      headers: {
        "X-API-KEY": "YOUR_API_KEY_HERE",
      },
    }
  );

  const data = await response.json();
  console.log(data.groups);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.chainpatrol.io/api/v2/organization/asset-groups",
      headers={
          "X-API-KEY": "YOUR_API_KEY_HERE",
      },
  )

  data = response.json()
  print(data["groups"])
  ```

  ```bash cURL theme={null}
  curl -X GET 'https://app.chainpatrol.io/api/v2/organization/asset-groups' \
    -H 'X-API-KEY: YOUR_API_KEY_HERE'
  ```
</CodeGroup>

## Response

### Success Response

```json theme={null}
{
  "groups": [
    {
      "id": 1,
      "name": "URLs",
      "assetCount": 25
    },
    {
      "id": 2,
      "name": "Wallets",
      "assetCount": 10
    },
    {
      "id": 3,
      "name": "Socials",
      "assetCount": 15
    },
    {
      "id": 4,
      "name": "Empty Group",
      "assetCount": 0
    }
  ]
}
```

### Response Fields

| Field                | Type   | Description                                           |
| -------------------- | ------ | ----------------------------------------------------- |
| groups               | array  | Array of group objects belonging to your organization |
| groups\[].id         | number | Unique identifier for the group                       |
| groups\[].name       | string | Display name of the group                             |
| groups\[].assetCount | number | Number of assets currently assigned to this group     |

## Error Responses

### 401 Unauthorized

Returned when the API key is missing, invalid, or doesn't have organization access:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key with organization access required"
  }
}
```

## Use Cases

### Display Group Statistics

```typescript theme={null}
async function displayGroupStats() {
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
    }
  );

  const { groups } = await response.json();

  console.log("Asset Group Statistics:");
  console.log("========================");

  groups.forEach((group) => {
    console.log(`${group.name}: ${group.assetCount} assets`);
  });

  const totalAssets = groups.reduce((sum, g) => sum + g.assetCount, 0);
  console.log(`\nTotal: ${totalAssets} assets across ${groups.length} groups`);
}
```

### Find Group by Name

```typescript theme={null}
async function findGroupByName(groupName: string) {
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
    }
  );

  const { groups } = await response.json();
  const group = groups.find((g) => g.name.toLowerCase() === groupName.toLowerCase());

  if (group) {
    console.log(`Found group "${group.name}" (ID: ${group.id}) with ${group.assetCount} assets`);
    return group;
  } else {
    console.log(`Group "${groupName}" not found`);
    return null;
  }
}

// Usage
findGroupByName("Wallets");
```

### Identify Empty Groups

```typescript theme={null}
async function findEmptyGroups() {
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
    }
  );

  const { groups } = await response.json();
  const emptyGroups = groups.filter((g) => g.assetCount === 0);

  if (emptyGroups.length > 0) {
    console.log(`Found ${emptyGroups.length} empty groups:`);
    emptyGroups.forEach((g) => console.log(`  - ${g.name} (ID: ${g.id})`));
  } else {
    console.log("No empty groups found");
  }

  return emptyGroups;
}
```

### Build Group Selector UI

```typescript theme={null}
interface GroupOption {
  value: number;
  label: string;
  count: number;
}

async function getGroupOptions(): Promise<GroupOption[]> {
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
    }
  );

  const { groups } = await response.json();

  return groups.map((group) => ({
    value: group.id,
    label: `${group.name} (${group.assetCount})`,
    count: group.assetCount,
  }));
}

// Usage in a UI framework
async function renderGroupSelector() {
  const options = await getGroupOptions();
  
  // Example for React/similar framework
  // return (
  //   <select>
  //     {options.map(opt => (
  //       <option key={opt.value} value={opt.value}>
  //         {opt.label}
  //       </option>
  //     ))}
  //   </select>
  // );
}
```

### Export Group Summary

```typescript theme={null}
async function exportGroupSummary() {
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
    }
  );

  const { groups } = await response.json();

  // Create CSV content
  const csvHeader = "Group ID,Group Name,Asset Count\n";
  const csvRows = groups
    .map((g) => `${g.id},"${g.name}",${g.assetCount}`)
    .join("\n");
  const csvContent = csvHeader + csvRows;

  // Save to file (Node.js)
  const fs = require("fs");
  fs.writeFileSync("group-summary.csv", csvContent);
  console.log("Group summary exported to group-summary.csv");
}
```

### Monitor Group Growth

```typescript theme={null}
async function monitorGroupGrowth() {
  const response = await fetch(
    "https://app.chainpatrol.io/api/v2/organization/asset-groups",
    {
      headers: { "X-API-KEY": "YOUR_API_KEY_HERE" },
    }
  );

  const { groups } = await response.json();

  // Sort by asset count
  const sortedGroups = [...groups].sort((a, b) => b.assetCount - a.assetCount);

  console.log("Groups by size (largest first):");
  sortedGroups.forEach((group, index) => {
    const percentage = groups.reduce((sum, g) => sum + g.assetCount, 0);
    const groupPercentage = ((group.assetCount / percentage) * 100).toFixed(1);
    console.log(
      `${index + 1}. ${group.name}: ${group.assetCount} assets (${groupPercentage}%)`
    );
  });
}
```

## Best Practices

### Caching

* Cache group lists when building UI dropdowns to reduce API calls
* Invalidate cache when groups are created, updated, or deleted
* Consider a cache TTL of 5-10 minutes for typical use cases

### Performance

* This endpoint returns all groups in a single request (no pagination needed)
* Groups are typically small in number (\< 100 for most organizations)
* Use this endpoint to build lookup tables for group ID to name mappings

### Integration

```typescript theme={null}
// Create a helper class for group management
class GroupManager {
  private apiKey: string;
  private cache: Map<number, { name: string; assetCount: number }> = new Map();
  private cacheTime: number = 0;
  private cacheTTL: number = 5 * 60 * 1000; // 5 minutes

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async getGroups(forceRefresh: boolean = false) {
    if (!forceRefresh && Date.now() - this.cacheTime < this.cacheTTL) {
      return Array.from(this.cache.values());
    }

    const response = await fetch(
      "https://app.chainpatrol.io/api/v2/organization/asset-groups",
      {
        headers: { "X-API-KEY": this.apiKey },
      }
    );

    const { groups } = await response.json();
    
    this.cache.clear();
    groups.forEach((g) => {
      this.cache.set(g.id, { name: g.name, assetCount: g.assetCount });
    });
    this.cacheTime = Date.now();

    return groups;
  }

  async getGroupName(groupId: number): Promise<string | null> {
    if (this.cache.has(groupId)) {
      return this.cache.get(groupId)!.name;
    }

    await this.getGroups();
    return this.cache.get(groupId)?.name || null;
  }

  invalidateCache() {
    this.cache.clear();
    this.cacheTime = 0;
  }
}

// Usage
const manager = new GroupManager("YOUR_API_KEY_HERE");
const groups = await manager.getGroups();
const groupName = await manager.getGroupName(1);
```

## Notes

* Organization is automatically determined from your API key
* All groups belonging to your organization are returned in a single response
* The `assetCount` reflects the current number of assets assigned to each group
* Groups with zero assets are still included in the response
* Group IDs are unique within your organization
* This endpoint does not support pagination as the number of groups is typically small


## OpenAPI

````yaml GET /organization/asset-groups
openapi: 3.0.3
info:
  title: ChainPatrol External API - OpenAPI 3.0
  description: ChainPatrol External API documentation
  version: 2.0.0
servers:
  - url: https://app.chainpatrol.io/api/v2
security: []
tags:
  - name: asset
  - name: report
externalDocs:
  url: https://chainpatrol.com/docs
paths:
  /organization/asset-groups:
    get:
      tags:
        - organization
      summary: List organization asset groups
      description: List all asset groups belonging to your organization with asset counts.
      operationId: organizationAssetGroupsList
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        name:
                          type: string
                        assetCount:
                          type: number
                      required:
                        - id
                        - name
                        - assetCount
                required:
                  - groups
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.NOT_FOUND'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      security:
        - ApiKey: []
components:
  schemas:
    error.BAD_REQUEST:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Invalid input data
        code:
          type: string
          description: The error code
          example: BAD_REQUEST
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Invalid input data error (400)
      description: The error information
      example:
        code: BAD_REQUEST
        message: Invalid input data
        issues: []
    error.UNAUTHORIZED:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Authorization not provided
        code:
          type: string
          description: The error code
          example: UNAUTHORIZED
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Authorization not provided error (401)
      description: The error information
      example:
        code: UNAUTHORIZED
        message: Authorization not provided
        issues: []
    error.FORBIDDEN:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Insufficient access
        code:
          type: string
          description: The error code
          example: FORBIDDEN
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Insufficient access error (403)
      description: The error information
      example:
        code: FORBIDDEN
        message: Insufficient access
        issues: []
    error.NOT_FOUND:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Not found
        code:
          type: string
          description: The error code
          example: NOT_FOUND
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Not found error (404)
      description: The error information
      example:
        code: NOT_FOUND
        message: Not found
        issues: []
    error.INTERNAL_SERVER_ERROR:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Internal server error
        code:
          type: string
          description: The error code
          example: INTERNAL_SERVER_ERROR
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Internal server error error (500)
      description: The error information
      example:
        code: INTERNAL_SERVER_ERROR
        message: Internal server error
        issues: []
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your API key. This is required by most endpoints to access our API
        programatically. Reach out to us at
        [support@chainpatrol.io](mailto:support@chainpatrol.io?subject=Re:%20API%20Key%20for%20SDK&body=Company:%20%0AName:%20%0APurpose:%20)
        to get an API key for your use.

````