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.

POSThttps://api.swarmz.net/functions/v1/platform-usage

Returns 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.

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": []
  },
  "balances": {
    "purchased_total": 0,
    "topup_available": 0,
    "included_remaining": 0,
    "rollover_remaining": 0,
    "by_workspace": [
      {
        "workspace_id": "<uuid>",
        "purchased_total": 0,
        "purchased_consumed": 0,
        "purchased_expired": 0,
        "topup_available": 0,
        "included_credits": 0,
        "included_used": 0,
        "included_remaining": 0,
        "rollover_credits": 0,
        "rollover_used": 0,
        "rollover_remaining": 0,
        "rollover_expiry": null,
        "caps": {
          "credits_per_day": null,
          "monthly_credit_cap": null,
          "monthly_credits": null,
          "rollover_months": null,
          "max_projects": null,
          "max_custom_domains": null,
          "max_published_projects": null,
          "cloud_budget_cap": null,
          "custom_domains_enabled": true,
          "max_compute_size": "small"
        }
      }
    ]
  }
}

usage is consumption over the period; balances is the point-in-time standing credit state. Field meanings:

Field	Meaning
`usage.credits_used`	Count of credits deducted over the period.
`usage.usd_credits`	Sum of the USD value stamped at each charge.
`usage.cloud_usd`	Sum of cloud cost over the period.
`usage.by_workspace[]`	Per-tenant breakdown: `{ workspace_id, credits_used, usd_credits, cloud_usd }`.
`balances.purchased_total`	Lifetime top-up credits purchased into the account's tenants.
`balances.topup_available`	Top-up credits still available to spend (never re-charged on consume).
`balances.included_remaining`	Unused monthly-grant credits remaining this cycle.
`balances.rollover_remaining`	Unused credits carried over from prior cycles.
`balances.by_workspace[]`	Per-tenant standing balance: purchased (total/consumed/expired), monthly grant (`included_`), rollover pool (`rollover_` + `rollover_expiry`), and the current plan `caps`.

See Credits for how each balance is charged and refreshed.

balances may be null

balances is additive and best-effort. If the standing-balance read fails it degrades to balances: null rather than failing the whole usage report — treat null as "unavailable", not "zero".

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`	underlying DB message	A read failed server-side (the failing read is one of the workspace lookup, `credit_transactions`, or `cloud_usage`); safe to retry
500	`internal_error`	—	Unexpected server-side failure; safe to retry

The usage_read_failed reason is the raw database error message of whichever read failed. A failure of the additive balances read never reaches the client — it degrades to balances: null (logged server-side, not returned as an error).

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.