Behavioral Metrics

See also: Behavioral Metrics concept and configuration for what this API powers, when to call it, and how it is configured.

GET /api/v1/behavioral-metrics

List all metric definitions with value counts. Supports cursor-based pagination.

Response

{
  "data": [
    {
      "id": "metric_001",
      "name": "impression_count_30d",
      "description": "Number of impressions in last 30 days",
      "aggregateFunction": "count",
      "sourceField": "impressions",
      "windowDays": 30,
      "computeMode": "batch",
      "batchIntervalMin": 60,
      "status": "active",
      "_count": { "values": 4521 },
      "createdAt": "2026-02-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "hasMore": false,
    "limit": 50,
    "cursor": null
  }
}

POST /api/v1/behavioral-metrics

Create a new metric definition. Maximum 20 metrics per tenant.

Request Body

Field	Type	Required	Description
`name`	string (1-100)	Yes	Unique metric name
`description`	string (≤ 500)	No	Description
`aggregateFunction`	enum	Yes	One of `"count"`, `"sum"`, `"avg"`, `"min"`, `"max"`, `"ratio"`
`sourceField`	enum	Yes	One of `"impressions"`, `"positive"`, `"negative"`, `"neutral"`, `"converts"`, `"totalValue"`
`windowDays`	integer (1-3650) \| null	No	Rolling window in days. `null` (or omitted) = all-time
`groupByDimensions`	array	No	Up to 4: the fixed keys `"offerId"`, `"channelId"`, `"creativeId"`, `"outcomeType"`, or any registered custom dimension key
`filterConditions`	object	No	Recursive condition group `{ logic: "and"\|"or", conditions: [...] }`. Leaf conditions are `{ field, operator, value }` with `operator` ∈ `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`.
`sqlFilter`	string (≤ 500)	No	Raw SQL WHERE clause filter
`computeMode`	enum	No	`"batch"` or `"realtime"`. Default: `"batch"`
`batchIntervalMin`	integer (5-1440)	No	Batch compute interval in minutes. Default: `60`

Realtime metrics only support count or sum aggregate functions — any other combination returns 400.

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": "impression_count_30d",
    "aggregateFunction": "count",
    "sourceField": "impressions",
    "windowDays": 30,
    "computeMode": "batch",
    "batchIntervalMin": 60
  }'

Response: 201 Created

Returns 409 Conflict if a metric with the same name already exists.

PUT /api/v1/behavioral-metrics

Update a metric definition.

Request Body

Field	Type	Required	Description
`id`	string (UUID)	Yes	Metric ID
All POST fields	—	No	Only provided fields are updated
`status`	enum	No	`"active"`, `"paused"`, or `"archived"`

Response: 200 OK

DELETE /api/v1/behavioral-metrics

Delete a metric definition. Fails if the metric is referenced by active contact policies or decisioning gates.

Parameter	Type	Required	Description
`id`	string	Yes	Metric ID (query parameter)

Response: 204 No Content

GET /api/v1/behavioral-metrics/

Get a metric definition with value count and last computed timestamp.

Response

{
  "id": "metric_001",
  "name": "impression_count_30d",
  "aggregateFunction": "count",
  "sourceField": "impressions",
  "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

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Behavioral Metrics

GET /api/v1/behavioral-metrics

Response

POST /api/v1/behavioral-metrics

Request Body

Example

PUT /api/v1/behavioral-metrics

Request Body

DELETE /api/v1/behavioral-metrics

GET /api/v1/behavioral-metrics/

Response

POST /api/v1/behavioral-metrics//compute

Response

GET /api/v1/behavioral-metrics//values

Query Parameters

Response

Roles

​GET /api/v1/behavioral-metrics

​Response

​POST /api/v1/behavioral-metrics

​Request Body

​Example

​PUT /api/v1/behavioral-metrics

​Request Body

​DELETE /api/v1/behavioral-metrics

​GET /api/v1/behavioral-metrics/

​Response

​POST /api/v1/behavioral-metrics//compute

​Response

​GET /api/v1/behavioral-metrics//values

​Query Parameters

​Response

​Roles

GET /api/v1/behavioral-metrics

Response

POST /api/v1/behavioral-metrics

Request Body

Example

PUT /api/v1/behavioral-metrics

Request Body

DELETE /api/v1/behavioral-metrics

GET /api/v1/behavioral-metrics/

Response

POST /api/v1/behavioral-metrics//compute

Response

GET /api/v1/behavioral-metrics//values

Query Parameters

Response

Roles