Analytics API
API endpoints for KPI trend analysis, Pareto charts, multi-KPI comparison, and cross-board benchmarking.
Overview
The Analytics API provides statistical analysis queries for KPI data. It supports single-KPI trend analysis with anomaly detection, multi-KPI comparison with normalization, Pareto analysis for root cause investigation, and cross-board KPI benchmarking.
All queries are scoped to the caller’s organization via organizationId from the authenticated session.
Get KPI Trend
Retrieve trend analysis data for a single KPI, including raw values, moving average, statistical summary, anomaly markers, and a linear regression trendline.
GET /api/trpc/analytics.getKpiTrend?input={"json":{"kpiDefinitionId":"kpi_01HXK5...","timeRange":"30d"}}
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
kpiDefinitionId | string | Yes | KPI definition ID to analyze |
startDate | string | No | Start date (ISO 8601). Overrides timeRange if both startDate and endDate are provided |
endDate | string | No | End date (ISO 8601) |
timeRange | string | No | Shorthand: 7d, 30d, 90d, 1y (default: 30d) |
windowSize | number | No | Moving average window size, 2-30 (default: 5) |
Response:
{
"result": {
"data": {
"json": {
"kpiDefinitionId": "kpi_01HXK5...",
"kpiName": "On-Time Delivery Rate",
"values": [
{
"id": "val_01HXK5...",
"date": "2026-03-01",
"value": 94.2,
"movingAvg": 93.8,
"isAnomaly": false
},
{
"id": "val_01HXK6...",
"date": "2026-03-08",
"value": 72.1,
"movingAvg": 89.4,
"isAnomaly": true
},
{
"id": "val_01HXK7...",
"date": "2026-03-15",
"value": 96.5,
"movingAvg": 91.2,
"isAnomaly": false
}
],
"stats": {
"mean": 87.6,
"stdDev": 10.4,
"p10": 72.1,
"p50": 94.2,
"p90": 96.5,
"count": 3
},
"trendline": {
"slope": 1.15,
"intercept": 84.3,
"r2": 0.12
},
"anomalies": [
{ "index": 1, "value": 72.1, "deviation": -2.3 }
]
}
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
values | array | Time-series data points with date, value, moving average, and anomaly flag |
stats.mean | number | Arithmetic mean of all values |
stats.stdDev | number | Standard deviation |
stats.p10 | number | 10th percentile |
stats.p50 | number | 50th percentile (median) |
stats.p90 | number | 90th percentile |
stats.count | number | Total number of data points |
trendline.slope | number | Linear regression slope (positive = improving for higher-is-better) |
trendline.intercept | number | Y-intercept of the regression line |
trendline.r2 | number | Coefficient of determination (0-1, higher = better fit) |
anomalies | array | Data points deviating more than 2 standard deviations from the mean |
Get Pareto Data
Perform Pareto analysis on a board column, ranking categories by frequency with cumulative percentages. Identifies the “vital few” categories that account for 80% of occurrences.
GET /api/trpc/analytics.getParetoData?input={"json":{"boardId":"brd_01HXK5...","columnId":"col_01HXK5...","timeRange":"90d"}}
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
boardId | string | Yes | Board to analyze |
columnId | string | Yes | Column whose values to count and rank |
timeRange | string | No | Filter items by creation date: 7d, 30d, 90d, 1y |
groupBy | string | No | Secondary grouping column |
categoryColumnId | string | No | Secondary column to filter by |
categoryFilterValue | string | No | Value in the category column to filter on |
teamFilter | string | No | Filter by assignee user ID |
Response:
{
"result": {
"data": {
"json": {
"categories": [
{
"category": "Equipment fault",
"frequency": 45,
"percentage": 36.0,
"cumulativePercentage": 36.0
},
{
"category": "Material defect",
"frequency": 30,
"percentage": 24.0,
"cumulativePercentage": 60.0
},
{
"category": "Operator error",
"frequency": 20,
"percentage": 16.0,
"cumulativePercentage": 76.0
},
{
"category": "Process drift",
"frequency": 12,
"percentage": 9.6,
"cumulativePercentage": 85.6
}
],
"total": 125,
"thresholdIndex": 3,
"vitalFewCount": 4
}
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
categories | array | Categories ranked by frequency (descending) |
categories[].category | string | Category label from the column value |
categories[].frequency | number | Number of items with this value |
categories[].percentage | number | Percentage of total (rounded to 2 decimals) |
categories[].cumulativePercentage | number | Running cumulative percentage |
total | number | Total count across all categories |
thresholdIndex | number | Index of the first category where cumulative % reaches 80% |
vitalFewCount | number | Number of categories that account for 80% of occurrences |
Results are bounded to 10,000 items per query to prevent performance issues on large boards. Use timeRange or teamFilter to narrow the dataset if needed.
Get Cross-Board KPI Comparison
Compare a named KPI across multiple boards within the organization. Returns per-board summaries with latest value, trend, mean, and status, plus an organization-wide benchmark.
GET /api/trpc/analytics.getCrossBoardKpiComparison?input={"json":{"kpiName":"OEE","timeRange":"30d"}}
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
kpiName | string | Yes | KPI name to compare across boards (case-insensitive match) |
boardIds | string[] | No | Restrict comparison to specific board IDs |
timeRange | string | No | Time window: 7d, 30d, 90d, 1y (default: 30d) |
Response:
{
"result": {
"data": {
"json": {
"kpiName": "OEE",
"boards": [
{
"boardId": "brd_01HXK5...",
"boardName": "Production Line 1",
"workspaceName": "Manufacturing",
"latestValue": 92.1,
"mean": 89.5,
"stdDev": 3.2,
"trend": {
"slope": 0.8,
"direction": "improving"
},
"status": "green",
"unit": "%",
"dataPoints": 12
},
{
"boardId": "brd_01HXK6...",
"boardName": "Production Line 2",
"workspaceName": "Manufacturing",
"latestValue": 84.7,
"mean": 82.3,
"stdDev": 5.1,
"trend": {
"slope": -0.3,
"direction": "declining"
},
"status": "amber",
"unit": "%",
"dataPoints": 12
}
],
"benchmark": 88.4,
"rankings": [
{ "boardId": "brd_01HXK5...", "boardName": "Production Line 1", "value": 92.1, "rank": 1 },
{ "boardId": "brd_01HXK6...", "boardName": "Production Line 2", "value": 84.7, "rank": 2 }
]
}
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
kpiName | string | The KPI name that was searched for |
boards | array | Per-board comparison data |
boards[].latestValue | number | Most recent KPI value |
boards[].mean | number | Average value over the time range |
boards[].stdDev | number | Standard deviation over the time range |
boards[].trend | object | Linear regression slope and direction |
boards[].status | string | Current traffic-light status: green, amber, red |
benchmark | number | Organization-wide average of latest values across all boards |
rankings | array | Boards ranked by latest value (direction-aware: highest first for higher-is-better) |
The KPI name matching is case-insensitive. “OEE”, “Oee”, and “oee” all match the same KPI definitions across boards.
The organizationId is always taken from the authenticated session context, never from client input. This prevents cross-tenant data leakage in the comparison results.