Concepts

The handful of objects you will meet in the API and the app, and the rules that make the numbers trustworthy.

Organization

The tenancy boundary. Your API keys, automations, runs, workspaces, roles, and reports all belong to one organization, and every API call is scoped to the key's organization. There is no cross-organization access, ever.

Localization

Each organization picks its own currency, locale, and time zone under Settings, and every money, number, and date renders accordingly, on the dashboard, in analytics, and on the shared QBR report (including the PDF).

• Currency drives the symbol and formatting of every money figure ($1,235 for USD, 1.235 € for EUR). LumaTrack stores values in the organization's currency and does not convert between currencies, so set the rates you enter in the same currency you choose here.
• Locale drives number grouping and the decimal separator (1,234.56 vs 1.234,56), the date order (May 9, 2026 vs 9 May 2026), and the interface language. Today the interface ships in US English and UK English, so an organization on English (United Kingdom) reads organisation where a US one reads organization. Locales without a translation yet fall back to US English text (more languages are groundwork-ready).
• Time zone is the zone run timestamps and period boundaries display in.

Defaults are US English, US Dollars, UTC. The setting is per organization, so an MSP's managed clients can each report in their own currency and conventions.

Workspace

Segmentation inside one organization: teams, departments, projects (say, "IT Operations" and "Security Operations"). Every automation lives in exactly one workspace, and most read endpoints accept a workspace filter.

Every organization has a Default workspace from day one. Creating, renaming, and deleting workspaces is available on Team and higher; the free tier works entirely inside Default, so upgrading later migrates nothing.

If you are an MSP, note the distinction: workspaces divide one company's own work. Client companies are separate managed organizations with their own logins, keys, and data. See the MSP guide.

Automation

One automated task, with two halves:

• The baseline: what the task costs a human. manual_minutes per occurrence, minus oversight_minutes a person still spends per automated run, priced at a job role's loaded rate or an explicit hourly rate.
• The cost side: build_cost, monthly_cost, run_cost, and optionally itemized cost components.

The API addresses automations by slug.

Status

An automation moves through a lifecycle, and status decides whether its runs realize value:

Status	Meaning
candidate	A manual task you are sizing. It projects ROI from your expected volume but realizes nothing; runs you send are stored and inform the projection, not the headline.
active	Running for real. Every non-held run counts toward realized value.
paused	Temporarily off. Existing realized value stays in the ledger; new runs are recorded but the automation is not expected to be producing.
retired	Decommissioned. Its history stays intact; it drops out of the active portfolio.

The honest trap to avoid: a candidate that is actually live still shows $0 realized until you set it active. The dashboard flags that case.

Savings classes

Every automation declares what kind of value it produces, and the ledger keeps the classes separate rather than blending them into one flattering number:

Class	Meaning
hard	Cash that stops leaving the building (license dropped, contractor hours cut)
cost_avoidance	Spend that would have happened and did not (an incident contained, an audit finding avoided)
productivity	Hours handed back to people (real, but it does not reduce payroll by itself)

The headline keeps these in separate lanes rather than summing them, because a CFO trusts $1 of hard savings differently from $1 of returned time. The productivity lane is also the only one discounted by the conservatism factor.

Evidence grades

How the baseline was established, so nobody mistakes an estimate for a measurement:

Grade	Meaning
measured	Timed or instrumented from real observation.
sampled	Spot-checked from a representative subset, not every case.
declared	An informed estimate by someone who knows the process.

The grade rides alongside the savings class on every report: it qualifies how much weight the number deserves. A declared baseline is still useful; it is just labeled as what it is.

Assumption freshness

Baselines age. If an automation's assumptions have not been confirmed or edited in 180 days, the app and the reports mark them stale until someone re-attests. Editing any baseline field counts as a review.

Run

One execution of one automation: status (success or failure), executed_at, optional duration_seconds, source, external_id, and arbitrary JSON metadata. Runs are the evidence; without them an automation is just a projection.

Two flags you will see on runs:

• held : the run arrived after your plan's monthly event cap. It is stored, visible, and excluded from value math until you upgrade or the month resets. Held is not dropped; nothing is ever silently dropped.
• backfilled : the run arrived through historical import rather than live ingest, and the provenance sticks. See Backfill.

AI runs can carry token usage; LumaTrack computes the dollar cost server-side from a maintained model price table and books it into the ledger's per-run cost bucket, version-stamped for auditability. See AI workloads.

Closed periods

Months freeze automatically 10 days after they end. A frozen month accepts no new run events (live or backfilled), so the number your CFO saw in January is still the number in March. Late evidence is welcome; submit it without executed_at and it lands in the current period instead.

Freezing is real, not cosmetic. Each period's value is written once to an internal ledger (one row per automation, per month, per cost/value bucket) and never rewritten after the month closes: editing an assumption, rate, or baseline later changes future and open months, never a closed one. Because the ledger is the system of record, the monthly rollups also outlive raw-event retention. Your plan may only keep raw run events for a window (90 days on Free), but the value those runs produced is preserved in the ledger for good. Dashboards and reports read the ledger, so the headline numbers are stable and reproducible.

Corrections: as-reported vs as-restated

Occasionally real evidence surfaces for a month that has already frozen. The classic case is a held over-cap event released after the month closed. The frozen figures still never change. Instead, LumaTrack books the late run as a signed correction against that month, valued at the month's frozen per-run rates, and keeps two honest views:

• As-reported: exactly what the frozen month published, forever.
• As-restated: as-reported plus corrections, so all-time totals still reconcile to the evidence.

Corrections come only from late-arriving runs. Editing a rate or an assumption never books one; an edit is a change of opinion, not new evidence, and the freeze applies to both views. On Business and Enterprise plans the Ledger page lists every correction with the as-reported figure it corrects (see the Ledger guide).

GET /api/v1/periods lists the frozen months for your organization.

The ledger

The ledger is the persisted system of record behind every figure LumaTrack shows. Realized value is decomposed into one signed row per automation, per month, per bucket:

Bucket	Sign	What it holds
Labor value	positive	Time saved by successful runs, valued at the rate (productivity already discounted by the realization factor)
stream:*	positive	Each value stream's accrued value, in its own lane
Per-run cost	negative	Per-run charges and metered usage, on every run (success or failure)
Recurring cost	negative	Monthly licenses and fees, allocated day-proportionally
Amortized cost	negative	Capitalized one-offs spread over their useful life
Build (one-time)	negative	Setup cost, booked in the activation month

Amounts are signed, so the net for any slice is simply their sum (net = gross value + costs). Every row also carries the savings class and evidence grade it counts under, and an assumption fingerprint: a short signature of the inputs (rate, minutes, class) used to compute it. If you edit an assumption, the fingerprint changes, the open months recompute, and the move is recorded as a restatement. Closed months never restate.

Choosing when an edit takes effect

When you change an economic input (rate, minutes, per-run or monthly cost), the edit form asks what the change applies to:

• All open months (default): the new values reprice every open month; the pre-edit history is not kept as a separate window.
• From today / from the start of this month / from a date: the pre-edit values are frozen into a dated window and stay in force for runs before the boundary; the new values apply from it onward. Use this when the price or the process genuinely changed on a date, rather than being wrong all along.

Whichever scope you pick, closed months keep their published figures. Build cost and other one-time or amortized costs are not windowed: an edit is always a correction of the amount, still booked at the original month and schedule (open months reprice, frozen months stand).

Variance, sensitivity, and NPV

On Business and Enterprise, Reports → Variance & planning decomposes each automation's monthly forecast miss into two honest parts: volume variance (the run-count miss, priced at the per-run value in force when the forecast froze) and rate variance (everything the ledger realized beyond that price). The two sum to the total miss exactly, so "we ran less" and "the value per run moved" can never hide inside one blended number. The same page bands each projection ±20% on its per-run value (sensitivity) and discounts it at your configurable annual rate (NPV; set the rate under Settings, next to the realization factor).

Dashboards, reports, and the API read these rows rather than recomputing from raw runs, which is what makes the headline numbers stable, fast, and able to outlive raw-event retention. The unfiltered ledger reconciles to your net value to date, to the cent.

You can audit all of it on the Ledger page in the app: filter by any permutation of the dimensions, group it, drill any figure down to its formula and the runs behind it, and export it. See the Ledger guide.

Audit log

Every admin action that changes who can see or move the numbers (settings edits, API keys minted or revoked, member invitations and role changes, webhooks, automation deletions, shared costs, report links) lands in an append-only audit log under Settings, with the actor and timestamp. The actor's email is kept even if the account is later removed. Free shows the last 30 days, Team 90; Business and Enterprise keep the full history.

Shared costs

(Business and Enterprise) Some spend belongs to the whole automation program, not one automation: the RPA platform license, the team's tooling. Record it under Settings → Shared costs and LumaTrack allocates each month's charge across your automations, weighted by run volume (or evenly), day-prorated over the cost's effective window. This is showback: the allocation appears on the Ledger page and in the finance export so finance can see who benefits, but it is never deducted from an automation's own numbers; those stay directly attributable. Shares always sum to the month's charge to the cent.

Job roles and rates

Hours saved are priced through job roles: a base hourly wage times a loading multiplier (default 1.43) for benefits and overhead. LumaTrack can seed roles from published BLS occupational wage medians, with the source cited on each; every value is overridable. Rate precedence per automation: explicit hourly_rate, then the assigned role's loaded rate, then the organization default.

Cost components

When build_cost plus monthly_cost plus run_cost is too coarse, itemize. Five kinds, each charged the way the money actually moves: one_time, recurring (per month), amortized (straight-lined over a set number of months), per_run, and per_unit (amount times units per run, which is how you model token costs).

A per_unit component carries a default units_per_run, but a run can report its actual consumption: pass usage on the run ingest, e.g. {"automation": "...", "usage": {"tokens": 1840}}, keyed by the component name. That run is then costed at its real units; runs that report no usage fall back to the default.

Baseline steps

manual_minutes is the simple case: the whole manual task, one number, one rate. When the manual process is really several steps done by different people, decompose it into baseline steps. Each step carries:

• a label ("Triage ticket", "Apply config", "Verify"),
• its own minutes,
• an optional role (by name) so each step is priced at that role's loaded rate (a junior triages, a senior signs off), and
• an occurrence_pct (0 to 100) for steps that do not happen every time ("the escalation step fires 20% of the time").

When an automation has steps, its baseline value per run is the sum across steps (minutes x occurrence% x role rate) instead of the single manual_minutes x rate. An automation with no steps is unchanged: the single-field path is just the one-step case, so simple stays simple. Manage steps over the API at /automations/{slug}/baseline-steps.

Oversight steps decompose the other side of the equation the same way: the human time still spent per automated run (review, approvals, exception handling). Each oversight step carries its own role, minutes, and occurrence, and is deducted from the baseline value. With no oversight steps an automation falls back to its single oversight_minutes field. Manage them at /automations/{slug}/oversight-steps.

Projection versions

A candidate's expected_runs_per_month is the forecast its projected ROI rests on. Each time you set or change that forecast, LumaTrack freezes a projection version (the value, the date it took effect, and a fingerprint of the assumptions in force). Versions are never edited; a change supersedes the old one with a newer row.

This is what keeps "did we hit our forecast" honest: variance is always measured against the version that was in force when the period started, so a forecast cannot quietly rewrite itself to match reality after the fact. The variance is a volume comparison (forecast runs vs actual runs), priced at the current per-run economics; rate drift is handled separately by assumption freshness. Read the history at GET /automations/{slug}/projection-versions.

Value streams

Labor saved is rarely the whole story. Value streams capture the credibility-classed extras an automation delivers on top of returned hours:

Type	Monthly value from
ticket_deflection	tickets_deflected_per_month x cost_per_ticket
downtime_reduction	incidents_per_month x (baseline_mttr_min - automated_mttr_min)/60 x downtime_cost_per_hour
sla_penalty_avoidance	breaches_avoided_per_period x penalty_per_breach
error_reduction	(baseline_error_rate - automated_error_rate) x volume_per_month x cost_per_error
audit_prep, cycle_time, revenue_protection, custom	an explicit monthly_value in params
toil_kpi	tracked but non-dollar (values at $0)

Each stream declares its own savings class (hard, cost_avoidance, or productivity), independent of the automation's class: a deflection stream shows as cost avoidance even on a productivity-class automation. Streams are additive and optional; an automation with none is valued on labor alone.

Recording a value stream

From the automation's page, open the Value beyond labor card and add a stream: choose its lane, the kind, and a realization factor. Every kind is available in the form. Flat-value kinds (custom, revenue_protection, audit_prep, cycle_time) take a single monthly figure: a retired $8,000/yr license is a custom stream in the hard lane at 666.67 per month. The measurable kinds (ticket_deflection, downtime_reduction, sla_penalty_avoidance, error_reduction) reveal the structured inputs their formula needs (the table above), and a live preview shows the resulting monthly value as you type. toil_kpi records a non-dollar KPI.

The same streams can be created over the API:

POST /api/v1/automations/{slug}/value-streams
{
  "type": "ticket_deflection",
  "savings_class": "cost_avoidance",
  "realization_factor": 0.8,
  "params": { "tickets_deflected_per_month": 12, "cost_per_ticket": 35 }
}

The realization factor

A stream's modeled value is rarely the value finance will actually credit, so every stream carries a realization factor between 0 and 1 that haircuts it:

reported monthly value = modeled monthly value x realization_factor

The deflection stream above models 12 x $35 = $420/month. At a realization factor of 0.8 (some of those tickets would have self-resolved, or the deflection is only partial) LumaTrack reports $336/month. A factor of 1 claims the full modeled value; 0.5 claims half; 0 records the stream for tracking but credits no dollars. Set it to the fraction a skeptical client CFO would accept rather than the optimistic ceiling.

The realization factor is per stream and applies in any lane, so it is how you discount a hard or cost-avoidance claim. It is distinct from the productivity conservatism factor: that one is organization-wide and discounts only productivity-lane labor dollars. Value streams are never touched by the conservatism factor; their own realization factor is the only haircut, whatever lane they report in.

Accrual and where it shows up

A stream accrues its realized value over the automation's live months within its effective_from/effective_to window, materialized through the ledger. So the monthly figure appears on the Value beyond labor card the moment you add it, while the amount that rolls into net savings builds up over the months the automation has been live.

Once recorded, a stream's dollars flow into its lane's total everywhere that total is read: the dashboard, the QBR report and its PDF, the MSP client book and portfolio analytics, the Value by savings class chart, and GET /api/v1/summary.

How the math behaves

A few rules worth knowing before you compare LumaTrack's numbers to a spreadsheet:

• Value realized per successful run is (manual_minutes minus oversight_minutes) at the hourly rate, or the sum across baseline steps when they are defined. Failed runs realize nothing and still pay their run costs.
• Productivity-lane dollar values are discounted by a conservatism factor, x0.50 by default. Finance teams discount time-saved claims because saved minutes do not all convert to productive work, so LumaTrack's headline is the number a skeptical CFO would compute. Hours stay physical; only their dollar value is discounted. Hard savings and cost avoidance are never discounted. The factor is per-organization (Settings) and is reported in GET /api/v1/summary as productivity_conservatism.
• First-year projections are tempered by an adoption ramp; a candidate is never credited with twelve perfect months.
• A run you place on hold stays out of every total until you release it, and once a month is closed it keeps the figures it was signed off with even if a late run or an edited assumption arrives afterward.
• All money math is exact decimal arithmetic, not floating point.