​

KPIs API

ProBeya provides a comprehensive KPI system organized around the SQCDP framework: Safety, Quality, Cost, Delivery, and People. Each KPI definition is attached to a board and supports manual/automated value entry, target management, time-series analysis, threshold-based alerting (green/amber/red), and SPC (Statistical Process Control) with control limits and capability indices.

​

Quick Start: Ingesting OEE from Your MES

Record a daily OEE measurement from your manufacturing execution system in a single call:

curl -X POST https://acme.probeya.com/api/v1/kpis/clx9kp001/values \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "value": 87.3,
    "date": "2026-04-13",
    "comment": "Line 2 down 45min for seal replacement. OEE recovery by 14:00.",
    "source": "mes_historian"
  }'

​

Endpoints

​

GET /api/v1/kpis

List all KPI definitions for a specific board, enriched with the latest value and active target for each.

tRPC: kpis.list | Scope: read:kpis | Org context: Required

Parameters:

curl -H "Authorization: Bearer probeya_sk_live_7f3a..." \
     "https://acme.probeya.com/api/v1/kpis?boardId=clx9bd001"

Response:

{
  "data": [
    {
      "id": "clx9kp001",
      "name": "OEE (Overall Equipment Effectiveness)",
      "category": "delivery",
      "unit": "%",
      "frequency": "daily",
      "direction": "higher_is_better",
      "dataSource": "manual",
      "boardId": "clx9bd001",
      "organizationId": "clx9abc123def",
      "thresholds": {
        "red": 65,
        "amber": 75,
        "green": 85
      },
      "latestValue": {
        "value": 82.5,
        "date": "2026-04-12",
        "status": "amber"
      },
      "activeTarget": {
        "targetValue": 90,
        "periodStart": "2026-01-01",
        "periodEnd": "2026-12-31"
      },
      "createdAt": "2026-02-01T10:00:00.000Z"
    },
    {
      "id": "clx9kp002",
      "name": "Right First Time",
      "category": "quality",
      "unit": "%",
      "frequency": "daily",
      "direction": "higher_is_better",
      "dataSource": "manual",
      "boardId": "clx9bd001",
      "organizationId": "clx9abc123def",
      "thresholds": {
        "red": 90,
        "amber": 95,
        "green": 98
      },
      "latestValue": {
        "value": 96.2,
        "date": "2026-04-12",
        "status": "amber"
      },
      "activeTarget": {
        "targetValue": 99.0,
        "periodStart": "2026-01-01",
        "periodEnd": "2026-06-30"
      },
      "createdAt": "2026-02-01T10:05:00.000Z"
    },
    {
      "id": "clx9kp003",
      "name": "Safety Incidents (LTI)",
      "category": "safety",
      "unit": "count",
      "frequency": "monthly",
      "direction": "lower_is_better",
      "dataSource": "manual",
      "boardId": "clx9bd001",
      "organizationId": "clx9abc123def",
      "thresholds": {
        "green": 0,
        "amber": 1,
        "red": 3
      },
      "latestValue": {
        "value": 0,
        "date": "2026-04-01",
        "status": "green"
      },
      "activeTarget": {
        "targetValue": 0,
        "periodStart": "2026-01-01",
        "periodEnd": "2026-12-31"
      },
      "createdAt": "2026-02-01T10:10:00.000Z"
    }
  ]
}

Errors:

​

POST /api/v1/kpis/:id/values

Record a single manual KPI measurement. Uses upsert semantics — if a value already exists for the same KPI and date, it is overwritten. The enteredById is automatically set to the authenticated user for audit trail compliance.

tRPC: kpis.setValue | Scope: write:kpis | Org context: Required

Parameters:

curl -X POST https://acme.probeya.com/api/v1/kpis/clx9kp002/values \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "value": 97.8,
    "date": "2026-04-13",
    "comment": "Reject on Line 1 was a labeling error, not product quality",
    "source": "manual"
  }'

Response:

{
  "data": {
    "id": "clx9kv120",
    "kpiDefinitionId": "clx9kp002",
    "value": 97.8,
    "date": "2026-04-13",
    "comment": "Reject on Line 1 was a labeling error, not product quality",
    "source": "manual",
    "enteredById": "clx9us001",
    "organizationId": "clx9abc123def",
    "createdAt": "2026-04-13T14:00:00.000Z"
  }
}

Side effects:

• Logs activity event with KPI name, value, and date
• Evaluates threshold alerts (red/amber/green) and sends notifications if breached
• Fires kpi.value_recorded webhook
• Invalidates Redis cache for KPI data

Errors:

​

POST /api/v1/kpis/:id/batch-values (tRPC: kpis.batchSetValues)

Record multiple measurements in a single call. Ideal for MES/SCADA integrations that push daily data for multiple dates or multiple KPIs. Scales linearly: 365 rows take approximately 200ms.

curl -X POST https://acme.probeya.com/api/v1/kpis/clx9kp001/batch-values \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      { "date": "2026-04-10", "value": 84.1, "source": "mes_historian" },
      { "date": "2026-04-11", "value": 86.7, "source": "mes_historian" },
      { "date": "2026-04-12", "value": 82.5, "source": "mes_historian" },
      { "date": "2026-04-13", "value": 87.3, "source": "mes_historian" }
    ]
  }'

Response:

{
  "data": {
    "inserted": 4,
    "kpiDefinitionId": "clx9kp001"
  }
}

​

Threshold Alerting

KPIs support automatic traffic-light evaluation based on configurable thresholds. When a new measurement breaches the red threshold, ProBeya sends a notification to relevant team members.

Example: OEE thresholds

Thresholds: red=65, amber=75, green=85 (higher_is_better)

OEE = 87.3% → GREEN  (87.3 >= 85)
OEE = 79.1% → AMBER  (79.1 >= 75 but < 85)
OEE = 62.4% → RED    (62.4 < 75) — notification sent

​

SQCDP Categories

​

Pharma Integration Scenarios

// cron-oee-sync.ts — runs nightly at 01:00
import { fetchOeeFromHistorian } from "./mes-client";

async function syncOee() {
  const yesterday = new Date(Date.now() - 86400000)
    .toISOString().slice(0, 10);

  // Fetch from PI Historian / OSIsoft / Ignition
  const oeeLine1 = await fetchOeeFromHistorian("LINE-1", yesterday);
  const oeeLine2 = await fetchOeeFromHistorian("LINE-2", yesterday);

  // Push to ProBeya
  await fetch("https://acme.probeya.com/api/v1/kpis/clx9kp001/values", {
    method: "POST",
    headers: {
      "Authorization": "Bearer probeya_sk_live_7f3a...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      value: oeeLine1.oee,
      date: yesterday,
      comment: `A=${oeeLine1.availability}% P=${oeeLine1.performance}% Q=${oeeLine1.quality}%`,
      source: "pi_historian",
    }),
  });
}

# Batch BX-4472 completed with 96.8% yield
curl -X POST https://acme.probeya.com/api/v1/kpis/clx9kp_yield/values \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "value": 96.8,
    "date": "2026-04-13",
    "comment": "Batch BX-4472 completed. Yield within spec.",
    "source": "mes_batch_record"
  }'

​

SPC (Statistical Process Control)

ProBeya includes a built-in SPC engine for advanced KPI analysis, accessible via the tRPC-only kpis.getControlChart procedure:

• Control limits calculated using standard Western Electric rules (X-bar, R-chart)
• Capability indices (Cp, Cpk) for process capability assessment
• Rule violations detected automatically: runs above/below center, trends, outliers
• Configurable via the spcConfig field on the KPI definition

Expected response time: 20-100ms depending on dataset size (SPC calculations are performed in-memory).

​

KPI Hierarchy

KPIs can be organized in parent-child relationships. A parent KPI’s value is automatically computed from its children (e.g., a site-level OEE computed from individual line OEEs). Use kpis.getTree to fetch the full hierarchy and kpis.recalculate to recompute parent values.

​

tRPC-Only KPI Procedures

​

Rate Limiting