Usage, budgets, and alerts
Workspace usage limits in Settings, plus the separate usage ledger, budgets, and alerts API.
Confluye tracks two usage surfaces. They do not share storage and are not reconciled automatically.
| Surface | Where | What it measures |
|---|---|---|
| Subscription limits | Settings → Subscription, GET /api/v1/usage/limits | Resource counts and summed run costCredits for the current calendar month |
| Usage ledger | /api/v1/usage/events, budgets, and alerts | Append-only priced events in micros, optional spend budgets |
Subscription usage (UI)
Open Settings → Subscription (/confluye/{slug}/settings/subscription). The page loads workspaceShell.usage.get (same payload as session GET /api/usage and v1 GET /api/v1/usage/limits).
The UI always displays plan name Enterprise when plan is internal-test, and billing status Included because billingEnabled is hardcoded false. There is no checkout, plan change, or payment flow.
Organization usage reports currently use UTC calendar days only. The timeZone query parameter
must be omitted or set to UTC; non-UTC IANA zones fail with 400 until rollups support local
calendar boundaries and DST conversion. This prevents a report from silently assigning usage to the
wrong day.
Limits are computed in getWorkspaceUsageSummary against a fixed internal-test catalog:
| Key | Label | Limit | Counted as |
|---|---|---|---|
credits | Execution credits | 10,000 | Sum of costCredits on workspace runs |
workflows | Workflows | 100 | All workflows, including trashed |
schedules | Scheduled tasks | 100 | Schedules |
apiKeys | API keys | 20 | API keys |
documents | Documents | 500 | Documents without trashedAt |
documentTokens | Document tokens | 1,000,000 | Sum of those documents' tokens |
tableRows | Table rows | 50,000 | Rows on all tables (trashed tables still count) |
Each limit has used, limit, remaining, percentUsed, and status: exceeded if used is greater than the limit, warning at ≥ 80%, otherwise ok. The period is the current local calendar month (periodStart / periodEnd).
Usage ledger, budgets, and alerts (API)
The ledger is not shown in Settings. Operators append events with a workspace API key. Success and error bodies use the contract envelope { ok, data|error, meta: { contractVersion: "api-contracts.v1", generatedAt } }.
Mutations require Idempotency-Key (24-hour replay window). Missing keys return 400 with error.code: "idempotency_key_invalid".
See Usage API.
Pricing
POST /api/v1/usage/events ignores client costMicros unless it matches the server quote. Token pricing version is pricing-2026-01-01. Known models use per-million input/output micros; unknown hosted models use 3,000,000 / 15,000,000. Providers ollama, vllm, local:codex, and local:claude-code quote zero. Image generation uses a separate catalog (image-pricing-2026-07-17) in code; the events POST path only calls token calculateUsageCost.
costCredits on serialized events is costMicros / 10_000.
Budgets and alerts
Budgets are unique per workspace + period (daily or monthly). New rows default to enabled: false and warningPercent: 80. Evaluation is on-demand via POST /api/v1/usage/alerts — no scheduler tick creates alerts.
For an enabled budget, spend is the ledger sumCost in the UTC day or UTC calendar month. If spend reaches warningPercent or 100 of limitMicros, an alert is created once per {workspaceId, budgetId, periodStart, threshold} eventKey. Re-evaluate returns created: [] for the same keys.
Authorization
| Path | Auth |
|---|---|
Settings Subscription / tRPC usage.get / GET /api/usage | Session; other workspaces only if the user is a member |
/api/v1/usage/* | Bearer API key; workspace scope required (403 otherwise) |
No extra Admin/Owner check on usage routes.