Skip to content

Analytics & Usage ​

Read the same conversation and token numbers your Studio dashboard shows, so you can render them in your own product — an internal ops screen, a customer-facing portal, or a weekly report — and the service-level figures you report against an SLA.

OperationEndpointScope
Dashboard summaryGET /api/v1/analytics/summaryanalytics:read
Conversations over timeGET /api/v1/analytics/conversations-over-timeanalytics:read
Volume by channelGET /api/v1/analytics/channel-breakdownanalytics:read
SLA metricsGET /api/v1/analytics/slaanalytics:read
Credit balanceGET /api/v1/billing/creditsanalytics:read
Token usageGET /api/v1/billing/usageanalytics:read

Choosing a window ​

Every operation here takes either days — a rolling window from 1 to 365 — or an explicit start_date / end_date pair. Send both and the explicit dates win, so a dashboard can page a fixed range without recomputing an offset on each request. Send neither and you get all time.

Summary ​

One request rather than three, because these are the numbers that usually share a screen.

bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/analytics/summary?days=30" \
  -H "Authorization: Bearer sk_…"
json
{
  "window": { "start_date": "2026-08-22T…", "end_date": null },
  "conversations": {
    "total": 1284, "active": 3, "resolved": 910,
    "escalated": 42, "abandoned": 329, "resolution_rate": 70.87
  },
  "tokens": { "input": 4120533, "output": 881204, "total": 5001737, "llm_calls": 9315 },
  "channels": [ { "channel": "whatsapp", "count": 731 }, { "channel": "web", "count": 402 } ]
}

resolution_rate is a percentage from 0 to 100, not a fraction.

active is counted live

Unlike every other figure in the response, active ignores your window. A dashboard asking how many conversations are happening means now, not "in the last thirty days".

Series ​

conversations-over-time returns data: one row per bucket with date, count and how many resolved. Pass interval as day (default), week or month.

channel-breakdown returns data rows of channel and count — conversations grouped by the channel they started on, busiest first.

SLA metrics ​

GET /api/v1/analytics/sla returns the service-level figures for your workspace — or for one agent — over any window, in one request. It is also available as the MCP tool get_sla_metrics. A key without analytics:read is refused with 403 insufficient_scope.

Query. The same days or start_date / end_date window as above (ISO 8601, both ends inclusive; explicit dates win). Omit all three for all time. Add agent_id to scope every figure to one agent. For a daily or monthly report, send that day's or month's window.

bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/analytics/sla?start_date=2026-10-01&end_date=2026-10-31" \
  -H "Authorization: Bearer sk_…"

The response has four blocks — first_audio, availability, usage and handoff — plus the window and agent_id it used.

Rates here are fractions

Every rate in this report is a fraction from 0 to 1, and null when nothing was counted. That is unlike resolution_rate in the summary, which is a percentage.

first_audio — how long a caller waits to hear the reply ​

For every caller turn on a voice call (phone and web voice), the time from the end of the caller's utterance to the first audio frame of the reply leaving Perfox — the moment that audio is handed to the phone carrier's media stream (phone) or to the call's audio track (web voice).

  • End of the caller's utterance is the moment the voice stack detected it: on speech-to-speech models, the caller's last recognised words (or the provider's end-of-speech signal); on the speech-recognition pipeline, the moment the recogniser finalised the utterance. A recogniser's own trailing-silence window comes before that moment and is not included.
  • Included: everything the caller waits through — model time, knowledge-base and tool lookups, speech synthesis. If the agent speaks a short "let me check" line during a lookup, that line is the first audio.
  • Not included: carrier network transit and the caller's handset playback after the audio leaves Perfox.
  • Turns Perfox starts itself — the greeting, a platform note — have no caller utterance and are never counted. Barge-in overlaps are never counted as negative latency.
  • The figure is two durations added together, so no two server clocks are ever compared.

It is reported as overall, by_source, by_channel (phone, web_voice) and by_day (UTC days that have samples), each with samples, p50_ms, p95_ms and avg_ms.

  • by_source.cache — the reply's first audio was served from the shared speech cache, so nothing was synthesised. by_source.llm — the audio was generated live.
  • Percentiles are exact: the value at position ⌊p·n⌋ of the samples sorted ascending (so the median of an even count is the higher middle value). The same rule applies however the report is answered.
  • store names where the samples were read from. truncated: true means the window held more than 200,000 samples and the figures cover the first 200,000 — narrow the window.
  • Samples exist from the release that introduced this measurement onward; earlier calls have none.

availability ​

Availability is derived from the outcome of every interaction in the window:

  • turn_success_rate = turns_answered ÷ (turns_answered + turns_failed). turns_answered counts every agent reply on every channel; turns_failed counts turns where the agent failed and the customer got the generic fallback message instead of an answer. A voice turn that goes unanswered is handled on the call (a repeat prompt, then a hand-off) and is not recorded as a failed turn.
  • phone_call_answer_rate = phone_calls_answered ÷ phone_calls, over phone calls that started in the window. A call is answered when the agent produced at least one reply within the maximum length of a voice session after the call started. A call whose agent never replied — including a caller who hung up before the first reply — is unanswered. Web voice calls are not included in this rate, and neither are phone calls a person handles from the operator console, where the AI never speaks to the caller.

usage ​

FieldWhat it counts
conversationsConversations that started in the window
voice_callsDistinct voice sessions (phone and web voice) billed in the window
voice_minutesThe billed duration of those sessions, in minutes (one decimal)
turnsAgent replies in the window, every channel
messagesCustomer messages plus agent replies in the window, every channel — the same definition as the Billing & Usage page

handoff ​

Over conversations that started in the window (at most the newest 5,000; truncated: true beyond that):

  • handed_off — conversations where a person was asked for (a transfer or a queue) or a person took over.
  • handoff_rate = handed_off ÷ conversations — the complement of the containment rate on the Analytics page.
  • transfers_requested, transfers_connected and transfer_success_rate (connected ÷ requested).

Per agent. With agent_id, a turn counts for the agent that produced it; a turn without that attribution counts for the agent the conversation belongs to. Conversation-level figures use the conversation's agent.

Credit balance ​

json
{ "balance": 45749.5, "balance_mc": 45749500, "low_balance": false, "out_of_credits": false }

balance is for display; balance_mc is the same figure in millicredits, the unit the ledger settles in — use it when you need exact arithmetic. low_balance reflects the threshold set on your workspace, and out_of_credits means spending is blocked.

A new workspace is not "out of credit"

A workspace with no wallet yet reports false for both flags. Not-yet-provisioned and empty are different states, and a client should not render a blocking paywall over the first one.

Token usage ​

Takes the same window arguments and returns the window it used, totals for the period (input_tokens, output_tokens, total_tokens, llm_calls) and a by_date series whose rows carry date, input_tokens, output_tokens, total_tokens and call_count.

Tokens and credits are related but not interchangeable: tokens are what was consumed, credits are the prepaid balance that consumption draws down.

These are the Studio's own numbers

Both surfaces read the same source. If a figure here disagrees with your dashboard, that is a bug worth reporting — not a difference in definition.