Usage summary

GET /api/v1/wallet/dashboard/usage-summary

Aggregate call usage and spend for a date window — the numbers behind the billing dashboard's summary tiles. Duration and minute metrics count connected calls only; success_rate is connected / total over calls that reached a terminal state.

You choose the window

There is no fixed "current billing period" — you pass an explicit from / to range. To show the current calendar month, pass the first of this month as from and the first of next month as to.

Query parameters

Param	Type	Required	Notes
`from`	date (`YYYY-MM-DD`)	✓	Inclusive lower bound on the call's `created_at`.
`to`	date (`YYYY-MM-DD`)	✓	Exclusive upper bound. The window is half-open: `[from, to)`.

Response

{
  "total_calls":           240,
  "connected_calls":       198,
  "total_billed_minutes":  416,
  "avg_duration_seconds":  63,
  "total_spend_usd":       "89.3200",
  "avg_cost_per_min_usd":  "0.2147",
  "success_rate":          0.825
}

Field	Type	Notes
`total_calls`	int	Calls that reached a terminal state (`completed` or `failed`) in the window.
`connected_calls`	int	Calls that completed with a non-zero duration.
`total_billed_minutes`	int	Whole-minute-ceiling billed minutes across connected calls.
`avg_duration_seconds`	int	Mean connected-call duration, rounded to the nearest second.
`total_spend_usd`	string	Total spend in USD, serialized as a decimal string.
`avg_cost_per_min_usd`	string	`total_spend_usd / total_billed_minutes`, decimal string.
`success_rate`	float	`connected_calls / total_calls`, a fraction in `0..1` (not a percentage).

USD fields are decimal strings

total_spend_usd and avg_cost_per_min_usd are returned as strings (e.g. "89.3200") to preserve exact decimal precision — parse them as decimals, not floats, before doing math.

Examples

curl "https://dashboard.zoxa.ai/api/v1/wallet/dashboard/usage-summary?from=2026-06-01&to=2026-07-01" \
  -H "X-API-Key: zsk_..."

import httpx

r = httpx.get(
    "https://dashboard.zoxa.ai/api/v1/wallet/dashboard/usage-summary",
    params={"from": "2026-06-01", "to": "2026-07-01"},
    headers={"X-API-Key": "zsk_..."},
)
summary = r.json()
print(summary["total_calls"], summary["total_spend_usd"])

Errors

Status	`detail`	When
`400`	`"No organization selected"`	The key's user has no organization selected.
`422`	array	`from` or `to` missing or not a valid `YYYY-MM-DD` date.

Daily spend breakdown — per-day spend split by cost category
GET /calls — per-call list with date, agent, and status filters

Query parameters

Response

Examples

Errors

Related

On this page