Usage report
A read-only roll-up of credit and cloud usage across your tenants, for reconciliation. Calendar-aligned, UTC, and safe to call repeatedly.
https://api.swarmz.net/functions/v1/platform-usageReturns a read-only usage roll-up across your tenants, for reconciliation. The endpoint mutates nothing and is safe to call as often as you like. Periods are UTC and calendar-aligned.
Unlike the other endpoints, the identifier is optional: omit it for an account-wide roll-up, or pass a tenant_id to restrict to one tenant.
Parameters
Prop
Type
Request
curl -X POST https://api.swarmz.net/functions/v1/platform-usage \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "period": "current_month" }'const res = await fetch('https://api.swarmz.net/functions/v1/platform-usage', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({ period: 'current_month' }),
});
const data = await res.json();import requests
res = requests.post(
"https://api.swarmz.net/functions/v1/platform-usage",
headers={"Authorization": "Bearer sk_live_..."},
json={"period": "current_month"},
)
data = res.json()Response
{
"ok": true,
"usage": {
"credits_used": 0,
"usd_credits": 0,
"cloud_usd": 0,
"period": {
"from": "2026-05-01T00:00:00.000Z",
"to": "2026-06-01T00:00:00.000Z",
"label": "current_month"
},
"by_workspace": []
}
}Field meanings:
| Field | Meaning |
|---|---|
credits_used | Count of credits deducted over the period. |
usd_credits | Sum of the USD value stamped at each charge. |
cloud_usd | Sum of cloud cost over the period. |
by_workspace[] | Per-tenant breakdown: { workspace_id, credits_used, usd_credits, cloud_usd }. |
A fresh account returns zeros and by_workspace: [] — that is not an error. An unknown or foreign tenant_id also yields zeros rather than a 404.
Errors
| Status | error | reason | When |
|---|---|---|---|
| 401 | unauthorized | — | See Authentication |
| 405 | method_not_allowed | — | Anything other than POST |
| 429 | rate_limited | per_key / per_ip | Rate limit hit — see Rate limits |
| 500 | usage_read_failed | workspace_lookup_failed / credit_transactions_failed / cloud_usage_failed | A read failed server-side; safe to retry |
Idempotency
Not applicable — usage is a pure read. See Idempotency.
Notes
Reconcile with usd_credits as stamped
usd_credits is the value stamped at charge time. Reconcile against it
directly rather than recomputing from credits_used, so historical charges
stay stable across the period. The authoritative wholesale invoice flows
through Stripe Billing Meters, not this endpoint; use platform-usage for
observability and your own reconciliation.
This endpoint is limited to 60 requests/min per key and 120/min per IP. See Rate limits.
Single sign-on
Mint a short-lived redirect that lands a web-host user in their dashboard, already logged in. Send their browser to it — mint a fresh token on every click.
Get the account billing summary
Account-wide (or single-tenant) consolidated billing snapshot — period usage, upcoming invoice, card on file, and recent invoices.