---
title: "Agent Analytics"
method: GET
path: "/voice/analytics/agent"
tags: ["Voice Agent Analytics"]
---

# Agent Analytics

`GET /voice/analytics/agent`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/analytics/agent`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### Agent Analytics

Everything the agent analytics view shows for one agent over a date range: headline numbers with an optional comparison to the previous period, a daily series, audience (locations, devices, traffic sources), leads, handoffs, action items, engagement, sentiment, topics, end reasons, satisfaction, call timing, languages and web versus phone. The response payload sits directly on data, not nested under a named key.

Leave out `start` for all time. A `start` more than 5 years before `end` is moved up to 5 years before `end`. A `start` after `end` returns 400. Rates are fractions from 0 to 1.

## Query parameters

- `agentId` string, required
- `start` string, date-time
- `end` string, date-time
- `tz` string
- `compare` boolean
- `includeTests` boolean

## Response `200`

OK

- object
  - `status` 'success'
  - `data` object
    - `range` object: The window the numbers cover.
      - `start` string, date-time, nullable: Start of the window. Null when you sent no `start`, which means all time.
      - `end` string, date-time: End of the window. Now when you sent no `end`.
      - `tz` string: The time zone used to bucket days, hours and weekdays.
      - `previousStart` string, date-time, nullable: Start of the comparison window. Null unless `compare` is true and `start` was sent.
      - `previousEnd` string, date-time, nullable: End of the comparison window, which is the current `start`. Null unless `compare` is true and `start` was sent.
    - `testCalls` object
      - `count` integer: Test calls placed from the dashboard in the window, counted whether or not they are included.
      - `included` boolean: Whether test calls are counted in the other numbers, matching `includeTests`.
    - `overview` object
      - `kpis` object
        - `conversations` integer
        - `completionRate` number: Completed conversations divided by all conversations, from 0 to 1.
        - `avgDurationSeconds` number
        - `returningCallers` integer: Callers in the window who called more than once, or who also called before the window.
      - `previousKpis` object, nullable: The same numbers for the comparison window. Null unless `compare` is true and `start` was sent.
        - `conversations` integer
        - `completionRate` number
        - `avgDurationSeconds` number
        - `returningCallers` integer
      - `overTime` object[]: One entry per day in the window, zero filled, in the requested time zone. Capped at the most recent 3,660 days. Empty when no `start` was sent and there are no conversations.
        - `date` string: Day as `YYYY-MM-DD`.
        - `conversations` integer
        - `web` integer
        - `phone` integer
    - `audience` object
      - `locations` object[]: Up to 10 locations with the most conversations.
        - `city` string, nullable
        - `region` string, nullable
        - `country` string, nullable: Country name.
        - `count` integer
      - `locationUnknown` integer: Conversations not counted in `locations`.
      - `devices` object: Web calls only. Phone calls carry no device data.
        - `withDeviceData` integer
        - `deviceTypes` object
          - `desktop` integer
          - `mobile` integer
          - `tablet` integer
        - `browsers` object[]: Up to 5 browsers.
          - `name` string
          - `count` integer
        - `os` object[]: Up to 5 operating systems.
          - `name` string
          - `count` integer
      - `sources` object[]: Up to 10 traffic sources for web calls.
        - `kind` 'page' | 'campaign' | 'direct': `campaign` when the call carried UTM tags, `page` when it came from a referring page, `direct` otherwise.
        - `label` string: The UTM source and campaign, or the referring host and path. Empty for `direct`.
        - `count` integer
    - `attention` object
      - `notJoined` integer: Web calls that ended before the caller said anything.
      - `unanswered` integer: Knowledge gaps for this agent still waiting for an answer. Not limited to the window.
    - `outcomes` object
      - `leads` object
        - `count` integer
        - `rate` number: Lead conversations divided by all conversations, from 0 to 1.
        - `fields` object[]: Up to 6 collected fields that were filled in most often.
          - `field` string
          - `count` integer
        - `latest` object[]: Up to 10 most recent conversations that collected data.
          - `conversationId` string
          - `createdAt` string
          - `name` string, nullable
          - `email` string, nullable
          - `phone` string, nullable
          - `summary` string, nullable
          - `mediaId` string, nullable
          - `folderId` string, nullable
      - `handoffs` object
        - `count` integer
        - `rate` number: Handed off conversations divided by all conversations, from 0 to 1.
        - `reasons` object[]: Up to 5 most common handoff reasons.
          - `reason` string
          - `count` integer
      - `actionItems` object
        - `conversations` integer
        - `rate` number: Conversations with action items divided by all conversations, from 0 to 1.
        - `recent` object[]: Up to 5 action items from the most recent conversations.
          - `conversationId` string
          - `createdAt` string
          - `item` string
    - `quality` object
      - `engagement` object[]: Always 4 buckets, in order: Bounce (0-1 turns), Brief (2-5), Engaged (6-15), Deep (16+).
        - `label` string
        - `minMessages` integer
        - `maxMessages` integer, nullable
        - `count` integer
        - `percentage` integer
        - `avgDurationSeconds` number
        - `sentimentBreakdown` object
          - `positive` integer
          - `neutral` integer
          - `negative` integer
          - `unanalyzed` integer
      - `sentiment` object
        - `positive` integer
        - `neutral` integer
        - `negative` integer
        - `unanalyzed` integer
      - `topTopics` object[]: Up to 10 key topics, lowercased.
        - `topic` string
        - `count` integer
      - `endReasons` object[]: Up to 10 reasons calls ended.
        - `reason` string
        - `count` integer
      - `satisfaction` object, nullable: Average post-call rating. Null when no call in the window was rated.
        - `average` number
        - `count` integer
    - `whenAndWho` object
      - `byHour` object[]: 24 entries, hour 0 to 23 in the requested time zone.
        - `hour` integer
        - `count` integer
      - `byWeekday` object[]: 7 entries, weekday 0 (Sunday) to 6 (Saturday) in the requested time zone.
        - `weekday` integer
        - `count` integer
      - `languages` object[]: Up to 10 caller languages.
        - `language` string
        - `count` integer
    - `channel` object
      - `web` object
        - `count` integer
        - `avgDurationSeconds` number
      - `phone` object
        - `count` integer
        - `avgDurationSeconds` number

## Other responses

- `400`: A query parameter failed validation
- `404`: Agent not found

## Changes

- **2026-10-19** `52d777e6d46e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/speakai/apis/speak-ai-api/changes/voice/analytics/agent/get.md)

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)