Incidents: what they cost¶

Vocabulary note: in the UI, loss occurrences are incidents: tickets, downtime, truck rolls, WAN outages. "Events" is the billing unit (runs and incidents share one monthly event budget). The API keeps its original paths and field names: incidents are recorded via POST /api/v1/events with an event_type slug.

Automations create value; incidents destroy it. Tickets, unplanned downtime, truck rolls, a WAN link dropping at a client site: each occurrence has a measurable cost, and LumaTrack books it the same way it books savings: per occurrence, role-priced, frozen once the month closes, and never blended into the savings figures.

Why track losses in a value platform? Because "14 unplanned truck rolls cost $4,120 this quarter" is the business case for the project, hardware, or managed service that prevents them, built on measured evidence instead of a vendor's estimate.

The per-event cost model¶

Each incident type carries the cost of one occurrence:

event cost = response labor (role-priced steps, occurrence-weighted)
           + fixed cost per event (travel, parts, vendor fee)
           + measured downtime × downtime rate × criticality factor

Three honesty rules, enforced by the engine:

Downtime dollars accrue only once downtime is measured. An unresolved event books its labor and fixed cost; downtime is added when you resolve the event with real minutes, never estimated.
No downtime rate = non-dollar mode. A school has no revenue per hour; it has lost instructional hours. Leave the rate blank and LumaTrack counts hours without inventing dollars.
The criticality factor (0.1–1) haircuts downtime dollars so an internal system can't claim revenue-system rates. It is printed in every breakdown.

Every capture records its source (sensor recipe, webhook, manual, ticket import), displayed everywhere the event appears; sensor-measured and tech-logged evidence are never conflated.

Recording incidents¶

curl -X POST https://YOUR-HOST/api/v1/events \
  -H "Authorization: Bearer $LUMATRACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "unplanned-truck-roll",
        "source": "monitor:rmm",
        "external_id": "rmm-7f3a-000412"
      }'

external_id makes ingestion idempotent: a sensor or webhook retry is a no-op, not a double-counted incident. Events share the monthly event budget with runs; over-cap events are held, never dropped. Like the runs endpoint, the response echoes an ignored_fields list when the payload carries keys the ingester does not know: downtime instead of downtime_minutes books a zero-downtime incident, and that must never be a silent success.

Resolve an event (stamps resolved_at, records measured downtime):

curl -X POST https://YOUR-HOST/api/v1/events/evt_XXXX/resolve \
  -H "Authorization: Bearer $LUMATRACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"downtime_minutes": 45}'

Once an event's month closes, its booked cost is frozen: late resolutions are refused, exactly as late run edits are.

Agents can do all of this over MCP: the record_event, resolve_event, and list_event_types tools call the exact same ingestion the REST endpoints use, and all three are available to ingest-scope keys.

Sensors and hardware¶

Anything that can send an HTTP POST can record an event: an n8n/Rewst flow watching a ticket queue, an RMM or monitoring alert firing when a remote fix fails or a link drops, or a physical sensor. Point the tool (or its logging backend) at POST /api/v1/events with an ingest-scoped API key and a stable external_id per trigger. That turns a raw alert into a dollarized, auditable incident record.

Turning incidents into a business case¶

Once a type has measured history, an initiative (Team plan and higher) turns it into the artifact you can hand to a board: "these incidents cost $X/month, this project costs $Y, payback in Z months." The projection is your measured trailing baseline times the reduction you expect, with the baseline window printed on the case rather than implied.

Marking an initiative implemented freezes that measured baseline. From then on, realized value is the frozen baseline minus the measured actual, month by month, and a month where incidents rose shows negative. Because the freeze is permanent, an initiative whose incident types have no measured history cannot be implemented at all: there is no baseline to freeze, and a frozen zero would judge a working mitigation against nothing forever. Record the incidents first, then implement.

From initiative to automation¶

Often the thing that mitigates an incident type is itself an automation: a sensor-driven workflow, an auto-remediation, a scheduled job. Rather than start a fresh automation and lose the measured history, an implemented initiative (Team plan and higher, builder role) offers Turn into automation, which carries the frozen baseline forward. Two paths, chosen per case:

Link – the automation represents the mechanism. It books nothing itself (it is cost-avoidance with no per-run minutes); the initiative keeps realizing avoided cost against its frozen baseline, month by month. Choose this when the automated mechanism keeps reducing incidents and the value is still measured as "fewer losses." The stream is metered in exactly one place, the initiative, so it is never double-counted on the automation.
Convert – the value becomes the automation's ordinary run-based savings (saved minutes per run). The initiative is marked automated and stops realizing; the automation is now the meter. Choose this when automating the task genuinely changes the meter from "fewer incidents" to "time saved per run."

Either way the new automation records where it came from: its detail page shows "From initiative: …" and carries the initiative's measured monthly baseline as its before-anchor, so the before/after story survives the handover.

Where realized value shows up¶

An initiative's realized avoided cost appears on the dashboard (a "Mitigation initiatives" panel listing each implemented or automated case with its frozen baseline, realized-to-date, and the automation it became) and in the executive summary report you can share as a link or print to PDF for a board review. Because a linked automation books nothing itself, this value sits beside your automation net savings, never blended into it: the board sees one continuous before/after story instead of two disconnected numbers.

Webhooks¶

event.recorded and event.resolved join the outbound webhook catalog; see Webhooks.