> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Behavioral Metrics

> Define and compute custom behavioral metrics with configurable aggregation functions, time windows, and batch or realtime compute modes.

<Note>
  **See also**: [Behavioral Metrics concept and configuration](/studio/behavioral-metrics) for what this API powers, when to call it, and how it is configured.
</Note>

<Frame caption="The Behavioral Metrics page.">
  <img src="https://mintcdn.com/kaireonai/l-jsUQlUEuA3B6hG/images/screenshots/behavioral-metrics-list.png?fit=max&auto=format&n=l-jsUQlUEuA3B6hG&q=85&s=a042a109c2ed5e5d475c4821243d5cb4" alt="Behavioral Metrics list view in the Studio module" width="1440" height="900" data-path="images/screenshots/behavioral-metrics-list.png" />
</Frame>

## GET /api/v1/behavioral-metrics

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

### Response

```json theme={null}
{
  "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](/studio/dimensions) 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`                                                                                                                                                             |

<Note>Realtime metrics only support `count` or `sum` aggregate functions — any other combination returns `400`.</Note>

### Example

```bash theme={null}
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`

<Warning>Returns `409 Conflict` if a metric with the same name already exists.</Warning>

***

## 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/{id}

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

### Response

```json theme={null}
{
  "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/{id}/compute

Trigger computation of metric values for all customers.

### Response

```json theme={null}
{
  "computed": true,
  "valueCount": 4521
}
```

***

## GET /api/v1/behavioral-metrics/{id}/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.

```json theme={null}
[
  {
    "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 |

See also: [Behavioral Metrics](/studio/behavioral-metrics)