Analytics API

Workspace-level aggregates with a workspace API key: summary, time series, fault trends, channels, agents, capture gaps, latency histogram, review queue and fault precision.

The analytics endpoints return the same aggregates the dashboard shows, ready for your own reporting. They are GET only, authenticate with a workspace API key, and are scoped to the key's workspace.

Time window

Most endpoints accept an optional window:

Query parameter	Meaning
`from`	ISO 8601, inclusive.
`to`	ISO 8601, exclusive.

Both are compared with the call's receipt time in UTC. Omit both for all time. Test calls are excluded from every aggregate.

Endpoints

GET/api/analytics/summary

Totals and averages for the window: calls by status, average health score, danger and warning fault counts, average completion and coverage, the top faults, plus the same numbers for the previous period of equal length for comparison.

{
  "period": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-16T00:00:00Z" },
  "calls": 1284,
  "completed": 1201,
  "failed": 3,
  "averageHealthScore": 78.4,
  "dangerCalls": 96,
  "topFaults": [ { "code": "AGENT_LATENCY", "count": 412 }, { "code": "REPETITION", "count": 158 } ],
  "previous": { "…": "same shape for the preceding period" }
}

GET/api/analytics/timeseries

Health and volume over time. bucket is day (default), week or month. Returns points[] with the bucket start, calls analysed and average health.

GET/api/analytics/faults/trend

Fault counts per code over time. bucket as above; top (default 8) limits the number of codes returned as series[], each with a count per bucket.

GET/api/analytics/channels

One row per channel: calls, average health, danger-call rate, coverage, P95 agent latency and top faults.

GET/api/analytics/agents

One row per agentId (with agentName and agentType): calls, average health, danger-call rate, average latency. top (default 50) limits rows; unattributedCalls counts calls without an agentId.

GET/api/analytics/capture-gaps

The slots most often missed (with miss rate and corrected rate) and the questions most often skipped (with skip rate), ranked by absolute misses. top (default 10). Slots in inactive case branches are excluded. See Slot capture.

GET/api/analytics/latency

Histogram of agent response latency across the window: bins with their bounds and counts, as one series per agent type where available. See Latency.

GET/api/analytics/review-queue

Completed, unreviewed calls ordered by lowest health score first. top (default 8, up to 50). Each item is a conversation summary.

GET/api/analytics/fault-precision

For each fault code, how often reviewers marked it confirmed versus false positive, as a false-positive rate. language restricts to calls in one language. See Golden set and calibration.

Channels

GET/api/workspaces/{workspaceId}/channels

The workspace's channels: id, name, phoneNumberE164, provider, status, evaluationTemplateId, ingestTokenCount, samplePercent, minDurationSec, language, createdAtUtc, updatedAtUtc. Token endpoints beneath a channel are not accessible with an API key.

Example: nightly export

A nightly job that pulls yesterday's summary and per-agent table into a warehouse needs two requests:

FROM=$(date -u -d "yesterday" +%Y-%m-%dT00:00:00Z)
TO=$(date -u +%Y-%m-%dT00:00:00Z)

curl -s "https://voicelens.app/api/analytics/summary?from=$FROM&to=$TO" -H "X-Api-Key: $VLK" > summary.json
curl -s "https://voicelens.app/api/analytics/agents?from=$FROM&to=$TO&top=200" -H "X-Api-Key: $VLK" > agents.json

For per-call detail, subscribe to the conversation.completed webhook instead of polling the list.

Errors

401 for a missing or invalid key, 403 for any write, 429 above 600 requests per minute per key.