Agent Metrics & Performance

Overview

Agent metrics give you per-agent and per-client performance data: call volume, booking rates, call duration, and AI-handled calls. Metrics are calculated from call history and stored monthly for fast retrieval and period-over-period comparison.

Agent Metrics

Endpoint: GET /admin/reports/agent-metrics/:agentId?clientId=xxx&year=2025&month=3

Returns metrics for a single agent in a specific period:

Field	Description
`agentId`	The agent identifier
`period`	`YYYY-MM`
`metrics`	Object containing call and booking data
`source`	How the metrics were derived (`computed`, `cached`, etc.)
`lastUpdated`	When metrics were last calculated

Metrics Object

Metric	Description
`inboundCalls`	Calls received by the agent
`outboundCalls`	Calls initiated by the agent
`totalCalls`	Inbound + outbound
`successfulBookings`	Calls that resulted in a booked appointment
`totalDuration`	Total call duration in seconds
`callsFromAI`	Calls handled by the AI agent without human transfer

Combined Client Metrics

Endpoint: GET /admin/reports/combined-metrics?clientId=xxx&year=2025&month=3

Aggregates metrics across all agents for a client:

Field	Description
`agentCount`	Number of agents with metrics
`agents`	Array of per-agent metrics
`totals`	Aggregated totals across all agents

Totals Object

Metric	Description
`totalInboundCalls`	Sum of all agent inbound calls
`totalOutboundCalls`	Sum of all agent outbound calls
`totalCalls`	Total calls across all agents
`totalSuccessfulBookings`	Total bookings across all agents
`totalDuration`	Total duration in seconds
`totalCallsFromAI`	Total AI-handled calls
`averageDuration`	`totalDuration / totalCalls` (rounded)
`overallSuccessRate`	`(totalSuccessfulBookings / totalCalls) × 100`

Period Comparison

Endpoint: GET /admin/reports/period-comparison?clientId=xxx&agentId=xxx&startPeriod=2025-02&endPeriod=2025-03

Compares a single agent's metrics between two periods. Useful for tracking improvement or decline over time.

Required Parameters

Parameter	Format
`clientId`	Client ID string
`agentId`	Agent ID string
`startPeriod`	`YYYY-MM` (earlier period)
`endPeriod`	`YYYY-MM` (later period)

Recalculating Metrics

If metrics appear stale or incorrect, you can trigger a recalculation from raw call history:

Endpoint: POST /admin/metrics/recalculate

Body:

{
  "clientId": "client_abc",
  "agentId": "agent_123",
  "year": 2025,
  "month": 3
}

This reprocesses all calls for the agent in the specified period and updates the stored metrics document.

Recalculation is an expensive operation. Use it sparingly — only when you suspect metrics drift or after data migrations.

Appointment Data Sync

The system can sync appointment data from GoHighLevel into agent metrics:

Endpoint: GET /admin/bootstrap/appointments/counts?clientId=xxx&year=2025&month=3

This pulls monthly booking counts from GHL and merges them with the local metrics. Run this when GHL appointment data needs to be backfilled or reconciled with call-based metrics.

Call Outcomes

Calls are tracked with statuses that determine booking success:

Status	Meaning
`booked_appointment`	Call resulted in a confirmed booking
`in_progress`	Call is currently active
`completed`	Call ended normally without booking
`no_answer`	Call was not picked up
`failed`	Call failed to connect

The booking/success rate in metrics is calculated from booked_appointment calls divided by total calls.

SMS Metrics

SMS activity is tracked alongside calls. While SMS metrics are not currently broken out in the agent metrics endpoints, they appear in the dashboard and can be queried through the call history with appropriate status filters.

Agent Comparison

To compare agents within a client:

Use GET /admin/reports/combined-metrics to get all agent metrics for a period.
Compare successfulBookings, averageDuration, and overallSuccessRate across agents.
Use GET /admin/reports/period-comparison to track individual agent trends over time.

Agent Metrics & Performance

On this page