Aggregated usage breakdown

Alpha

GEThttps://api.voxrouter.ai/v1/usage

Aggregate the caller's organization's recent wallet ledger (commit + void rows) into a usage summary: totals, per-provider cost, per-error-code count, and a recent-events list. Same shape the dashboard's /app/usage page renders. Auth: `vr_session_*` tokens only. `pk_*` keys can already see their own credit activity via `/v1/credits/activity`; this is the org-level aggregated management view.

bash

curl https://api.voxrouter.ai/v1/usage \
  -H "Authorization: Bearer $VOXROUTER_API_KEY"

Headers

AuthorizationstringRequired

Bearer token. Send as Authorization: Bearer pk_....

Query parameters

daysintegerOptionalDefaults to 30

Window size in days (1–365). Default 30.

limitintegerOptionalDefaults to 100

Max ledger rows to read before aggregation (1–1000). Default 100.

Response

Aggregated usage summary.

json

{
  "totals": {
    "requests": 0,
    "costMicros": 0,
    "errorCount": 0
  },
  "byProvider": [
    {
      "provider": "string",
      "requests": 0,
      "costMicros": 0
    }
  ],
  "byErrorCode": [
    {
      "code": "string",
      "count": 0
    }
  ],
  "recent": [
    {
      "id": "string",
      "createdAt": "string",
      "status": "ok",
      "costMicros": 0
    }
  ]
}

totalsobjectRequired

byProviderobject[]Required

byErrorCodeobject[]Required

recentobject[]Required

Errors

Non-2xx responses return a JSON body with a machine-readable error code and an optional details string.

Status	Meaning
400	Request body failed validation or model string is malformed.
401	Missing or invalid API key.
403	The caller belongs to more than one organization, so org scope cannot be inferred. The CLI must select an org explicitly with `voxrouter org use <slug>` before retrying.