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.

Operation	Endpoint	Scope
Dashboard summary	GET /api/v1/analytics/summary	analytics:read
Conversations over time	GET /api/v1/analytics/conversations-over-time	analytics:read
Volume by channel	GET /api/v1/analytics/channel-breakdown	analytics:read
Credit balance	GET /api/v1/billing/credits	analytics:read
Token usage	GET /api/v1/billing/usage	analytics: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.

curl "https://<your-workspace>-api.perfox.ai/api/v1/analytics/summary?days=30" \
  -H "Authorization: Bearer sk_…"

{
  "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.

Credit balance

{ "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.