Operations

Usage and retention recovery

Reconcile the usage ledger, recover in-memory stores, and run observability retention.

Use this when subscription numbers disagree with the ledger, alerts never fire, audit rows vanish, or trash items reappear after restart.

Two usage systems

GET /api/v1/usage/limits (and Settings → Subscription) sums run costCredits and resource counts. /api/v1/usage/events is a separate append-only ledger. Workflow execution does not automatically POST ledger events. Do not expect the two totals to match unless you ingest events yourself.

GET /api/v1/usage/reconciliation?legacyCostCredits= compares ledger sumCost (optional dateFrom/dateTo) to legacyCostCredits * 10_000 micros. status: "mismatch" means they differ; there is no auto-repair write.

Persistence

Ledger, budgets, and alerts use Prisma only when DATABASE_URL is set (or PLATFORM_STORE=prisma). Otherwise they are process memory. Hosted preview/production throws if those surfaces need Prisma and DATABASE_URL is empty.

Confirmation: Settings → Workers persistence line (durable vs memory only). After a restart, empty GET /api/v1/usage/events with a workspace key means the memory store was lost — re-append with the same eventKey + Idempotency-Key (dedup 200) or new keys.

Alerts not appearing

PUT /api/v1/usage/budgets with enabled: true and positive limitMicros (Idempotency-Key required). Defaults leave budgets disabled.
POST /api/v1/usage/alerts — nothing else evaluates alerts (no scheduler).
Spend is UTC day or UTC month of occurredAt on ledger events, not subscription credits.
Duplicate thresholds reuse eventKey; created stays empty. GET /api/v1/usage/alerts still lists open rows.

Idempotency and validation

Symptom	Check
`400` `idempotency_key_invalid`	Send `Idempotency-Key` on POST events, PUT budgets, POST alerts
`400` cost/pricing mismatch	Omit `costMicros` / `pricingVersion` or match `pricing-2026-01-01`
`409` eventKey conflict	Same key, different payload — use a new `eventKey`
`400` invalid cursor / limit	Cursor must decode; `limit` 1–100

Observability retention

POST /api/observability/retention (session, Owner only) runs runObservabilityRetention:

Deletes runLog and workflowRunTrace older than FLUXUS_RUN_DETAIL_RETENTION_DAYS (default 30).
Nulls input/output on terminal runs past that cutoff.
Deletes auditEvent rows older than FLUXUS_AUDIT_RETENTION_DAYS (default 365).

Both env vars clamp to 1–3650. Response: { retention: { runDetailCutoff, auditCutoff, deletedLogs, deletedTraces, scrubbedRuns, deletedAuditEvents } }. There is no v1 equivalent. This does not purge Recently Deleted items.

Recently deleted / trash

Expired labels do not delete rows. Workflow and table trash on Prisma is in-memory; after restart, items can look active again. Documents/folders/knowledge bases persist trashedAt. Restore with PATCH ... { "trashed": false } or the Settings button.

Workspace file backups expire ~30 days after deletionRequestedAt via the file GC job — unrelated to Settings → Recently Deleted.

Confirmation checklist

Workspace API key: usage 401/403 otherwise.
Limits UI: plan internal-test, billingEnabled false, no enforcement.
Ledger ok: true and string costMicros.
After enabling a budget, POST alerts once and GET alerts.
Owner retention POST only when you intend to delete old logs/audit rows.
Do not paste decrypted secrets or provider keys into tickets.

Next steps

Usage API

Exact routes and envelopes.

Audit logs

List and retention.