AI Voice Agent Usage

Usage endpoints return customer-facing AI Voice Agent billing totals for a date range. They are intended for customer dashboards, invoices, and usage alerts. The public response exposes session counts, billed minutes, total charge, runtime type, and billing status. It does not expose provider costs or margin details.

Usage By Runtime and Billing Status

Endpoint	Method	Auth
/v1/ai/usage	GET	Required

Query parameters:

Parameter	Type	Description
from	date or RFC3339	Optional start. Defaults to 30 days ago. Date-only values start at midnight UTC.
to	date or RFC3339	Optional end. Defaults to now. Date-only values are exclusive of the next UTC day.

curl -sS 'https://api.minivoice.eu/v1/ai/usage?from=2026-07-01&to=2026-07-08' \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-07-09T00:00:00Z",
  "count": 2,
  "data": [
    {
      "runtime_type": "turn_based",
      "billing_status": "settled",
      "sessions_count": 42,
      "billed_minutes": 126,
      "total_charge": "1.260000"
    },
    {
      "runtime_type": "realtime",
      "billing_status": "pending",
      "sessions_count": 3,
      "billed_minutes": 9,
      "total_charge": "0.090000"
    }
  ]
}

Usage Summary

Endpoint	Method	Auth
/v1/ai/usage/summary	GET	Required

curl -sS 'https://api.minivoice.eu/v1/ai/usage/summary?from=2026-07-01T00:00:00Z&to=2026-07-08T00:00:00Z' \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "data": {
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-07-08T00:00:00Z",
    "sessions_count": 45,
    "billed_minutes": 135,
    "total_charge": "1.350000",
    "billing_status_breakdown": {
      "pending": 3,
      "settled": 42
    }
  }
}

Common Use Case

For a customer dashboard, show the summary number at the top and the grouped usage table below it. Use from and to consistently between the two endpoints so totals reconcile.

{
  "dashboard_card": {
    "label": "AI Voice Agent usage this week",
    "sessions_count": 45,
    "billed_minutes": 135,
    "total_charge": "1.350000"
  }
}

Common Failure

{
  "error": {
    "code": "invalid_date_range",
    "message": "to must be after from"
  }
}

Testing

Run the endpoints with no query parameters, then with a date-only range, then with an RFC3339 range. Confirm your parser treats numeric-looking charges as strings because the API returns charge values as strings.