Usage & quotas

RuleFlow meters two kinds of billable activity per tenant, per calendar month (period, "YYYY-MM"): workflow_execution (one unit per StartExecution call) and decision_simulation (one unit per successful stored-decision simulate call). Metering is best-effort — a metering write failure never blocks or fails the request it’s recording, the same posture the audit log takes.

Your tenant’s usage

GET /usage?from=2026-01&to=2026-08

from/to are both optional "YYYY-MM" bounds; omit both for the full history.

curl -sS "$RULEFLOW_API/api/usage?from=2026-06&to=2026-07" \
  -H "Authorization: Bearer $TOKEN"

{
  "periods": [
    { "period": "2026-06", "kind": "workflow_execution", "count": 412 },
    { "period": "2026-06", "kind": "decision_simulation", "count": 96 },
    { "period": "2026-07", "kind": "workflow_execution", "count": 208 }
  ]
}

Admin: every tenant’s usage

GET /admin/usage?period=2026-07

Requires the admin role — this is a deliberate, documented exception to “every operation is tenant-scoped,” reserved for cross-tenant reporting. Every route under /admin/* inherits this same gate. period is required; omitting it returns 400.

curl -sS "$RULEFLOW_API/api/admin/usage?period=2026-07" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

{
  "tenants": [
    { "tenant": "acme", "kinds": [
      { "period": "2026-07", "kind": "workflow_execution", "count": 208 },
      { "period": "2026-07", "kind": "decision_simulation", "count": 40 }
    ] },
    { "tenant": "globex", "kinds": [
      { "period": "2026-07", "kind": "workflow_execution", "count": 15 }
    ] }
  ]
}

A non-admin caller gets 403.

Quota behavior — 429

Starting an execution first reserves a slot against the tenant’s monthly execution limit. The limit is either a per-tenant override (tenants.max_executions_per_month, when set to a positive value on the tenant’s registry record) or the deployment’s process-wide default. Once the limit is reached for the current period, further StartExecution calls return:

HTTP 429
{ "error": "monthly execution quota exceeded (max 2)" }

The reservation happens before the runtime call, so a started execution always consumes a slot even if the downstream call subsequently fails — the slot is not refunded. A suspended tenant (status: "suspended" on its registry record) is rejected with 403 before a slot is ever reserved.

A separate quota guards artifact storage: creating a decision/workflow artifact that would push the tenant’s total stored bytes over MaxArtifactBytesPerTenant returns 429 (enforced on create only). A release-count quota (MaxReleasesPerProject) works the same way on release creation.

Admin: tenant registry

The tenant registry backs the per-tenant execution limit above and carries billing terms (money fields are always integer cents, never floats). Also admin-only.

curl -sS -X PUT "$RULEFLOW_API/api/admin/tenants/acme" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme Corp", "plan_code": "business", "status": "active",
    "base_cents": 250000, "included_executions": 5000, "overage_cents_per_1000": 8000,
    "currency": "BRL", "max_executions_per_month": 5000, "contact_email": "billing@acme.com"
  }'

{
  "tenant": "acme", "display_name": "Acme Corp", "plan_code": "business", "status": "active",
  "base_cents": 250000, "included_executions": 5000, "overage_cents_per_1000": 8000,
  "currency": "BRL", "max_executions_per_month": 5000, "contact_email": "billing@acme.com",
  "notes": "", "created_at": "2026-07-21T18:00:00Z"
}

plan_code must be one of trial, starter, business, ent-bridge, ent-silo; status must be active or suspended; all cents/count fields must be >= 0. The {tenant} path parameter always wins over any tenant field in the body. max_executions_per_month: 0 means “fall back to the deployment’s process-wide quota,” not “unlimited.” Provisioning is audited as tenant.provisioned on first write, tenant.updated on subsequent ones.