> ## 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 average first response time

> Returns the average time of the first response per contact within the specified date range

## Overview

Get the average time it takes for your team to send the first response to new customer messages within a specific date range. This critical metric helps you measure customer service quality and SLA compliance.

First response time is one of the most important customer service metrics, directly impacting customer satisfaction and retention.

## Use Cases

* **SLA Monitoring**: Track compliance with response time SLAs
* **Customer Satisfaction**: Monitor key customer experience metric
* **Team Performance**: Measure overall team responsiveness
* **Trend Analysis**: Compare first response times across different periods
* **Improvement Tracking**: Monitor the impact of process changes
* **Reporting**: Generate executive reports on customer service quality

## 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                                       |
| ------------ | --------- | -------- | ------------------------------------------------- |
| `startDate`  | string    | No       | Start date (ISO 8601 format). Default: 7 days ago |
| `endDate`    | string    | No       | End date (ISO 8601 format). Default: today        |
| `agentIds`   | string\[] | No       | Filter by specific team member IDs                |
| `pipelineId` | string    | No       | Filter by specific pipeline                       |

<Note>
  **Default Range**: If no dates provided, returns data for the last 7 days.
</Note>

## Response Structure

| Field                      | Type   | Description                                |
| -------------------------- | ------ | ------------------------------------------ |
| `averageFirstResponseTime` | number | Average first response time in **seconds** |

## Example Requests

### Get Last 7 Days (Default)

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

### Get Specific Date Range

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time?startDate=2024-09-01&endDate=2024-09-30' \
  --header 'x-api-key: your_api_key_here'
```

### Filter by Pipeline and Team Members

```bash theme={null}
curl --request GET \
  'https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time?pipelineId=550e8400-e29b-41d4-a716-446655440000&agentIds=member-1,member-2' \
  --header 'x-api-key: your_api_key_here'
```

## Example Response

```json theme={null}
{
  "averageFirstResponseTime": 300
}
```

This means the average first response time is **300 seconds** (5 minutes).

## Common Use Cases

### 1. Display Response Time Metric

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

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

  const minutes = Math.floor(averageFirstResponseTime / 60);
  const seconds = averageFirstResponseTime % 60;

  console.log(`⏱️ Average First Response Time: ${minutes}m ${seconds}s`);

  // Display as badge
  const status =
    averageFirstResponseTime < 300
      ? '🟢 Excellent'
      : averageFirstResponseTime < 600
        ? '🟡 Good'
        : '🔴 Needs Improvement';

  console.log(`Status: ${status}`);

  return { averageFirstResponseTime, minutes, seconds, status };
};
```

### 2. Compare Different Time Periods

```javascript theme={null}
const compareMonthlyPerformance = async () => {
  // Last month
  const lastMonthStart = new Date();
  lastMonthStart.setMonth(lastMonthStart.getMonth() - 1);
  lastMonthStart.setDate(1);

  const lastMonthEnd = new Date();
  lastMonthEnd.setDate(0);

  const lastMonthResponse = await fetch(
    `https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time?startDate=${lastMonthStart.toISOString().split('T')[0]}&endDate=${lastMonthEnd.toISOString().split('T')[0]}`,
    {
      headers: { 'x-api-key': 'your_api_key_here' },
    },
  );

  const lastMonth = await lastMonthResponse.json();

  // This month
  const thisMonthStart = new Date();
  thisMonthStart.setDate(1);

  const thisMonthResponse = await fetch(
    `https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time?startDate=${thisMonthStart.toISOString().split('T')[0]}`,
    {
      headers: { 'x-api-key': 'your_api_key_here' },
    },
  );

  const thisMonth = await thisMonthResponse.json();

  const improvement =
    lastMonth.averageFirstResponseTime - thisMonth.averageFirstResponseTime;

  console.log('📈 Monthly Comparison:');
  console.log(
    `Last Month: ${Math.floor(lastMonth.averageFirstResponseTime / 60)}m`,
  );
  console.log(
    `This Month: ${Math.floor(thisMonth.averageFirstResponseTime / 60)}m`,
  );
  console.log(
    `${improvement > 0 ? '✅ Improved' : '⚠️ Slower'} by ${Math.floor(Math.abs(improvement) / 60)}m`,
  );

  return { lastMonth, thisMonth, improvement };
};
```

### 3. SLA Compliance Check

```javascript theme={null}
const checkSLACompliance = async (slaMinutes = 5) => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  const actualMinutes = averageFirstResponseTime / 60;
  const compliant = actualMinutes <= slaMinutes;

  console.log(`SLA Target: ${slaMinutes} minutes`);
  console.log(`Actual: ${actualMinutes.toFixed(2)} minutes`);
  console.log(`Status: ${compliant ? '✅ Compliant' : '❌ Non-Compliant'}`);

  return {
    slaMinutes,
    actualMinutes,
    compliant,
    difference: actualMinutes - slaMinutes,
  };
};
```

### 4. Compare Team Member Performance

```javascript theme={null}
const compareTeamMemberPerformance = async (memberIds) => {
  const results = [];

  for (const memberId of memberIds) {
    const response = await fetch(
      `https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time?agentIds=${memberId}`,
      {
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    const data = await response.json();
    results.push({
      memberId,
      firstResponseTime: data.averageFirstResponseTime,
    });
  }

  // Sort by fastest
  results.sort((a, b) => a.firstResponseTime - b.firstResponseTime);

  console.log('Team Member First Response Time Comparison:');
  results.forEach((r, idx) => {
    console.log(
      `${idx + 1}. Member ${r.memberId}: ${Math.floor(r.firstResponseTime / 60)}m`,
    );
  });

  return results;
};
```

### 5. Weekly Performance Report

```javascript theme={null}
const getWeeklyReport = async () => {
  const today = new Date();
  const weekAgo = new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000);

  const response = await fetch(
    `https://api.vambe.me/api/analytics/team/snapshot/average-first-response-time?startDate=${weekAgo.toISOString().split('T')[0]}&endDate=${today.toISOString().split('T')[0]}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  const report = {
    period: 'Last 7 Days',
    startDate: weekAgo.toISOString().split('T')[0],
    endDate: today.toISOString().split('T')[0],
    averageFirstResponseSeconds: averageFirstResponseTime,
    averageFirstResponseMinutes: (averageFirstResponseTime / 60).toFixed(2),
    rating:
      averageFirstResponseTime < 180
        ? 'Excellent (< 3min)'
        : averageFirstResponseTime < 300
          ? 'Good (< 5min)'
          : averageFirstResponseTime < 600
            ? 'Fair (< 10min)'
            : 'Needs Improvement (> 10min)',
  };

  console.log('📊 Weekly Performance Report:', report);

  return report;
};
```

## Date Format

Dates should be in **ISO 8601 format** (YYYY-MM-DD):

* ✅ Correct: `"2024-09-30"`
* ✅ Correct: `"2024-01-15"`
* ❌ Incorrect: `"09/30/2024"`
* ❌ Incorrect: `"30-09-2024"`

## Time Zone Considerations

* Dates are interpreted in your account's configured time zone
* Response time calculations respect your business hours
* Default date range: Last 7 days from current time

## Error Responses

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

## Performance Benchmarks

Typical first response time benchmarks:

| Time Range   | Rating        | Use Case                    |
| ------------ | ------------- | --------------------------- |
| \< 3 minutes | Excellent ⭐⭐⭐ | Premium support, urgent     |
| 3-5 minutes  | Good ⭐⭐       | Standard support            |
| 5-10 minutes | Fair ⭐        | Non-urgent inquiries        |
| > 10 minutes | Needs Work ⚠️ | Consider staffing/processes |

## Related Endpoints

* [GET /api/analytics/team/snapshot/agent-distribution](/reference/analytics/get-agent-distribution) - Current workload distribution
* [Analytics Overview](/docs/analytics) - Complete analytics guide

## Notes

* **First Response Only**: Measures time to FIRST team member response per conversation
* **Team Average**: Aggregates across all team members (or filtered subset)
* **Seconds Unit**: Response time returned in seconds
* **Default Period**: Last 7 days if no dates specified
* **Business Impact**: Lower times generally correlate with higher satisfaction


## OpenAPI

````yaml get /api/analytics/team/snapshot/average-first-response-time
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/average-first-response-time:
    get:
      tags:
        - Team Analytics
      summary: Get average first response time
      description: >-
        Returns the average time of the first response per contact within the
        specified date range
      operationId: GetSnapshotTeamAnalyticsController_getAverageFirstResponseTime
      parameters:
        - name: startDate
          required: false
          in: query
          description: Start date (ISO 8601). Defaults to today-7d 00:00.
          schema:
            example: '2025-05-27'
            type: string
        - name: endDate
          required: false
          in: query
          description: End date (ISO 8601). Defaults to today 23:59.
          schema:
            example: '2025-06-03'
            type: string
        - 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: false
          in: query
          description: Optional boolean to filter by unassigned conversations
          schema:
            type: boolean
            example: true
        - name: x-api-key
          in: header
          description: API key
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved average first response time
          content:
            application/json:
              schema:
                type: object
                properties:
                  averageFirstResponseTime:
                    type: number
                    description: Average first response time in seconds
                    example: 300

````