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

# Get team member distribution of open conversations

> Returns the distribution of open conversations across different agents with average waiting time

## Overview

Get the distribution of open conversations across your team members, including how many conversations each agent has and their average waiting time. This provides a snapshot of current workload distribution and helps identify bottlenecks.

Perfect for real-time monitoring of team workload and ensuring balanced distribution of conversations.

## Use Cases

* **Workload Dashboard**: Monitor current workload across team
* **Load Balancing**: Identify agents with too many/few conversations
* **Assignment Decisions**: Determine which agent to assign new conversations to
* **Performance Monitoring**: Track average waiting time per agent
* **Team Management**: See who's handling conversations and how quickly
* **Capacity Planning**: Understand team capacity and bottlenecks

## Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

```
x-api-key: your_api_key_here
```

## Query Parameters

| Parameter        | Type      | Required | Description                                   |
| ---------------- | --------- | -------- | --------------------------------------------- |
| `agentIds`       | string\[] | No       | Filter by specific team member IDs            |
| `pipelineId`     | string    | No       | Filter by specific pipeline                   |
| `stageIds`       | string\[] | No       | Filter by specific stages                     |
| `hideArchived`   | boolean   | No       | Hide archived conversations (default: true)   |
| `hideUnassigned` | boolean   | No       | Hide unassigned conversations (default: true) |

## Response Structure

| Field               | Type  | Description                         |
| ------------------- | ----- | ----------------------------------- |
| `agentDistribution` | array | Array of agent distribution objects |

### Team Member Distribution Object

| Field                | Type          | Description                                               |
| -------------------- | ------------- | --------------------------------------------------------- |
| `agent_id`           | string (UUID) | Team member's unique identifier                           |
| `agent_name`         | string        | Team member's full name                                   |
| `count`              | number        | Number of open conversations assigned to this team member |
| `averageWaitingTime` | number        | Average waiting time in milliseconds                      |

## Example Request

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution' \
  --header 'x-api-key: your_api_key_here'
```

### With Filters

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution?pipelineId=550e8400-e29b-41d4-a716-446655440000&hideArchived=true' \
  --header 'x-api-key: your_api_key_here'
```

## Example Response

```json theme={null}
{
  "agentDistribution": [
    {
      "agent_id": "228d7a0d-9072-4ca8-939b-959b75cc606a",
      "agent_name": "Maria Rodriguez",
      "count": 15,
      "averageWaitingTime": 1800000
    },
    {
      "agent_id": "338e8b1e-8183-5db9-a4ab-a6ab86dd717b",
      "agent_name": "Carlos Silva",
      "count": 8,
      "averageWaitingTime": 900000
    },
    {
      "agent_id": "448f9c2f-9294-6eca-b5bc-b7bc97ee828c",
      "agent_name": "Ana Martinez",
      "count": 23,
      "averageWaitingTime": 3600000
    }
  ]
}
```

## Common Use Cases

### 1. Find Team Member with Least Workload

```javascript theme={null}
const findMemberWithLeastWorkload = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  // Sort by count ascending
  const sortedByWorkload = agentDistribution.sort((a, b) => a.count - b.count);

  const leastBusy = sortedByWorkload[0];

  console.log(`Team member with least workload: ${leastBusy.agent_name}`);
  console.log(`Current conversations: ${leastBusy.count}`);

  return leastBusy;
};
```

### 2. Display Workload Dashboard

```javascript theme={null}
const displayWorkloadDashboard = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  console.log('📊 Team Workload Distribution\n');

  agentDistribution.forEach((member) => {
    const avgMinutes = Math.floor(member.averageWaitingTime / 1000 / 60);
    const workloadLevel =
      member.count > 20
        ? '🔴 High'
        : member.count > 10
          ? '🟡 Medium'
          : '🟢 Low';

    console.log(`${member.agent_name}:`);
    console.log(`  Conversations: ${member.count} ${workloadLevel}`);
    console.log(`  Avg Wait Time: ${avgMinutes} minutes\n`);
  });

  return agentDistribution;
};
```

### 3. Balance Workload Alert

```javascript theme={null}
const checkWorkloadBalance = async (maxDifference = 10) => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  const counts = agentDistribution.map((a) => a.count);
  const max = Math.max(...counts);
  const min = Math.min(...counts);
  const difference = max - min;

  if (difference > maxDifference) {
    console.warn(`⚠️ Workload imbalance detected!`);
    console.warn(`Difference: ${difference} conversations`);
    console.warn(`Max: ${max} | Min: ${min}`);
    return { balanced: false, difference };
  }

  console.log('✅ Workload is balanced');
  return { balanced: true, difference };
};
```

### 4. Filter by Pipeline

```javascript theme={null}
const getSalesTeamWorkload = async (salesPipelineId) => {
  const response = await fetch(
    `https://api.vambe.me/api/analytics/team/snapshot/agent-distribution?pipelineId=${salesPipelineId}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  console.log(
    `Sales team handling ${agentDistribution.reduce((sum, a) => sum + a.count, 0)} conversations`,
  );

  return agentDistribution;
};
```

## Average Waiting Time

The `averageWaitingTime` field is in **milliseconds**. To convert:

```javascript theme={null}
const millisToMinutes = (millis) => Math.floor(millis / 1000 / 60);
const millisToHours = (millis) => Math.floor(millis / 1000 / 60 / 60);

// Usage
agent.averageWaitingTime = 1800000;
console.log(`${millisToMinutes(agent.averageWaitingTime)} minutes`); // 30 minutes
```

## Filters Explanation

* **`agentIds`**: Comma-separated list to filter specific team members
* **`pipelineId`**: Show only conversations in a specific pipeline
* **`stageIds`**: Show only conversations in specific stages
* **`hideArchived`**: Exclude archived conversations (default: true)
* **`hideUnassigned`**: Exclude unassigned conversations (default: true)

## Error Responses

| Status Code | Description                                  |
| ----------- | -------------------------------------------- |
| 400         | Bad Request - Invalid parameters             |
| 401         | Unauthorized - Invalid or missing API key    |
| 500         | Internal Server Error - Something went wrong |

## Related Endpoints

* [GET /api/analytics/team/snapshot/average-first-response-time](/reference/analytics/get-average-first-response-time) - Team average first response
* [GET /api/public/team-members/all](/reference/team-members/get-all-team-members) - Get list of all team members

## Notes

* **Real-time Snapshot**: Returns current state of open conversations
* **Only Active Team Members**: Team members with no conversations won't appear
* **Waiting Time**: Time since last customer message
* **Milliseconds**: All time values in milliseconds


## OpenAPI

````yaml get /api/analytics/team/snapshot/agent-distribution
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/analytics/team/snapshot/agent-distribution:
    get:
      tags:
        - Team Analytics
      summary: Get team member distribution of open conversations
      description: >-
        Returns the distribution of open conversations across different agents
        with average waiting time
      operationId: GetSnapshotTeamAnalyticsController_getAgentDistribution
      parameters:
        - name: agentIds
          required: false
          in: query
          description: Optional array of agent IDs to filter by specific agents
          schema:
            example:
              - agent-id-1
              - agent-id-2
            type: array
            items:
              type: string
        - name: pipelineId
          required: false
          in: query
          description: Optional pipeline ID to filter by specific pipeline
          schema:
            example: pipeline-id-1
            type: string
        - name: stageIds
          required: false
          in: query
          description: Optional array of stage IDs to filter by specific stages
          schema:
            example:
              - stage-id-1
              - stage-id-2
            type: array
            items:
              type: string
        - name: hideArchived
          required: false
          in: query
          description: Optional boolean to filter by archived conversations
          schema:
            type: boolean
            example: true
        - name: hideUnassigned
          required: true
          in: query
          schema:
            type: boolean
        - name: x-api-key
          in: header
          description: API key
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved agent distribution
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentDistribution:
                    type: array
                    items:
                      type: object
                      properties:
                        agent_id:
                          type: string
                          description: Agent ID
                          example: agent-123
                        agent_name:
                          type: string
                          description: Agent name
                          example: John Doe
                        count:
                          type: number
                          description: Number of open conversations assigned to this agent
                          example: 15
                        averageWaitingTime:
                          type: number
                          description: >-
                            Average waiting time in milliseconds for
                            conversations assigned to this agent
                          example: 1800000

````