KPI Definitions

Aggregate fleet metrics for performance analysis and reporting

KPI (Key Performance Indicator) definitions specify how to aggregate data from missions and incidents into meaningful metrics. These metrics help track fleet performance over time—mission success rates, area covered, incident frequency, and more.

KPI definitions are only supported at the account level.

When to Use

• Performance dashboards: Display aggregated metrics in mission widgets
• Success tracking: Calculate mission completion and success rates
• Utilization metrics: Track active robots, missions per day, etc.
• Custom aggregations: Build fleet-specific metrics from mission data fields

Spec Fields

Field	Type	Required	Description
label	string	Yes	Human-readable label for dashboards.
unit	string	No	Unit of measurement (e.g., "%", "meters", "seconds").
objectType	string	Yes	Object type to aggregate: "mission" or "incident".
field	string	Yes	Field to aggregate.
aggregation	string	Yes	Aggregation function (see below).
intervalMinutes	number	No	Time window for aggregation (e.g., 1440 for daily).
secondAggregation	string	No	Secondary aggregation applied after the first.
filters	array	No	Filters to apply before aggregation.

Aggregation Functions

Function	Description
SUM	Sum of all values
AVG	Average of all values
MIN	Minimum value
MAX	Maximum value
COUNT	Count of records
COUNT_DISTINCT	Count of unique values

Filter Operators

Operator	Description
=	Equals
!=	Not equals
>	Greater than
<	Less than
>=	Greater than or equal
<=	Less than or equal

Available Fields

Common Fields (all object types)

Field	Description
id	Object ID
entityId	Robot/entity ID
entityType	Entity type
type	Object type
startTime	Start timestamp
endTime	End timestamp
data.label	Object label
data.duration	Duration in milliseconds
data.estimatedDistance	Estimated distance covered

Mission-Specific Fields

Field	Description
data.state	Mission state string
data.status	Mission status (ok, error, warn)
data.isSuccess	Boolean success flag
data.isSuccessNum	Numeric success (1 or 0) — useful for AVG
data.incidentsCount	Number of incidents during mission
data.completedPercent	Completion percentage (0-1)
data.data_${key}	Custom mission data fields

Examples

Mission Success Rate

kind: KpiDefinition
apiVersion: v0.1
metadata:
  scope: account/<accountId>
  id: "mission-success-rate"
spec:
  label: "Mission Success Rate"
  unit: "%"
  objectType: "mission"
  field: "data.isSuccessNum"
  aggregation: "AVG"

Total Area Covered

kind: KpiDefinition
apiVersion: v0.1
metadata:
  scope: account/<accountId>
  id: "total-area-covered"
spec:
  label: "Total Area Covered"
  unit: "m²"
  objectType: "mission"
  field: "data.data_Area Covered"
  aggregation: "SUM"
  filters:
    - field: "data.state"
      operator: "="
      value: "completed"

Completed Missions Count

kind: KpiDefinition
apiVersion: v0.1
metadata:
  scope: account/<accountId>
  id: "completed-missions"
spec:
  label: "Completed Missions"
  objectType: "mission"
  field: "id"
  aggregation: "COUNT"
  filters:
    - field: "data.state"
      operator: "="
      value: "completed"

Average Active Robots Per Day

Uses two-stage aggregation: count unique robots per day, then average across days.

kind: KpiDefinition
apiVersion: v0.1
metadata:
  scope: account/<accountId>
  id: "active-robots-per-day"
spec:
  label: "Avg Active Robots"
  objectType: "mission"
  field: "entityId"
  aggregation: "COUNT_DISTINCT"
  intervalMinutes: 1440  # 24 hours
  secondAggregation: "AVG"
  filters:
    - field: "data.state"
      operator: "="
      value: "completed"

Average Mission Duration

kind: KpiDefinition
apiVersion: v0.1
metadata:
  scope: account/<accountId>
  id: "avg-mission-duration"
spec:
  label: "Avg Mission Duration"
  unit: "min"
  objectType: "mission"
  field: "data.duration"
  aggregation: "AVG"
  filters:
    - field: "data.state"
      operator: "="
      value: "completed"

Incident Count by Severity

kind: KpiDefinition
apiVersion: v0.1
metadata:
  scope: account/<accountId>
  id: "critical-incidents"
spec:
  label: "Critical Incidents"
  objectType: "incident"
  field: "id"
  aggregation: "COUNT"
  filters:
    - field: "severity"
      operator: "="
      value: "SEV 0"

Related Documentation

• Mission Tracking — Configure mission data capture
• Dashboards — Display KPIs in mission widgets