GET /api/v1/behavioral-metrics
List all metric definitions with value counts. Supports cursor-based pagination.
Response
{
"data": [
{
"id": "metric_001",
"name": "purchase_frequency_30d",
"description": "Number of purchases in last 30 days",
"aggregateFunction": "count",
"sourceField": "purchase",
"windowDays": 30,
"computeMode": "batch",
"batchIntervalMin": 60,
"status": "active",
"_count": { "values": 4521 },
"createdAt": "2026-02-01T10:00:00.000Z"
}
],
"total": 8,
"hasMore": false
}
POST /api/v1/behavioral-metrics
Create a new metric definition. Maximum 20 metrics per tenant.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Unique metric name |
description | string | No | Description |
aggregateFunction | string | Yes | "count", "sum", "avg", "min", "max" |
sourceField | string | Yes | Source interaction field to aggregate |
windowDays | integer | No | Rolling window in days (null = all-time) |
groupByDimensions | array | No | Dimension fields to group by |
filterConditions | object | No | Filter conditions for the aggregation |
sqlFilter | string | No | Raw SQL WHERE clause filter |
computeMode | string | No | "batch" or "realtime". Default: "batch" |
batchIntervalMin | integer | No | Batch compute interval in minutes. Default: 60 |
Realtime metrics only support count or sum aggregate functions.
Example
curl -X POST https://playground.kaireonai.com/api/v1/behavioral-metrics \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"name": "purchase_frequency_30d",
"aggregateFunction": "count",
"sourceField": "purchase",
"windowDays": 30,
"computeMode": "batch",
"batchIntervalMin": 60
}'
201 Created
PUT /api/v1/behavioral-metrics
Update a metric definition.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | Metric ID |
| All POST fields | — | No | Only provided fields are updated |
status | string | No | "active" or "paused" |
200 OK
DELETE /api/v1/behavioral-metrics
Delete a metric definition. Fails if the metric is referenced by active contact policies or qualification rules.
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Metric ID (query parameter) |
204 No Content
GET /api/v1/behavioral-metrics/
Get a metric definition with value count and last computed timestamp.
Response
{
"id": "metric_001",
"name": "purchase_frequency_30d",
"aggregateFunction": "count",
"sourceField": "purchase",
"windowDays": 30,
"computeMode": "batch",
"_count": { "values": 4521 },
"lastComputedAt": "2026-03-16T02:00:00.000Z"
}
POST /api/v1/behavioral-metrics//compute
Trigger computation of metric values for all customers.
Response
{
"computed": true,
"valueCount": 4521
}
GET /api/v1/behavioral-metrics//values
List computed metric values. Optionally filter by customer.
Query Parameters
| Parameter | Type | Description |
|---|
customerId | string | Filter values for a specific customer |
Response
Returns top 20 values sorted by value descending.
[
{
"id": "mv_001",
"metricId": "metric_001",
"customerId": "CUST001",
"value": 12,
"computedAt": "2026-03-16T02:00:00.000Z"
}
]
Roles
| Endpoint | Allowed Roles |
|---|
GET /behavioral-metrics | admin, editor, viewer |
POST /behavioral-metrics | admin, editor |
PUT /behavioral-metrics | admin, editor |
DELETE /behavioral-metrics | admin, editor |
GET /{id} | admin, editor, viewer |
POST /{id}/compute | admin, editor |
GET /{id}/values | admin, editor, viewer |
