> ## 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.

# Interaction Summary

> Aggregated interaction analytics grouped by offer, creative, channel, or customer.

The Interaction Summary API provides pre-aggregated analytics from the materialized interaction-summary store. Falls back to on-the-fly SQL aggregation from the raw interaction-history log if no materialized data exists.

## GET /api/v1/interaction-summary

Get aggregated interaction data grouped by a chosen dimension.

### Query Parameters

| Parameter | Type    | Required | Default  | Description                                                      |
| --------- | ------- | -------- | -------- | ---------------------------------------------------------------- |
| `groupBy` | string  | No       | `action` | Grouping dimension: `action`, `treatment`, `channel`, `customer` |
| `days`    | integer | No       | `30`     | Lookback window in days                                          |
| `limit`   | integer | No       | `100`    | Maximum results (capped at 500)                                  |
| `offset`  | integer | No       | `0`      | Offset for pagination                                            |

### Response -- `groupBy=action`

```json theme={null}
{
  "groupBy": "action",
  "days": 30,
  "summary": [
    {
      "id": "off_001",
      "name": "Premium Card Upgrade",
      "issue": "Revenue Growth",
      "group": "Credit Cards",
      "status": "active",
      "priority": 90,
      "impression": 1250,
      "click": 87,
      "dismiss": 45,
      "accept": 0,
      "convert": 32,
      "total": 1414,
      "ctr": 6.96,
      "cvr": 2.56,
      "positive": 87,
      "negative": 45,
      "neutral": 1118
    }
  ],
  "total": 15,
  "limit": 100,
  "offset": 0
}
```

### Response -- `groupBy=treatment`

```json theme={null}
{
  "groupBy": "treatment",
  "days": 30,
  "summary": [
    {
      "id": "cr_001",
      "name": "Email Variant A",
      "offerName": "Premium Card Upgrade",
      "channelType": "email",
      "channelName": "Marketing Email",
      "templateType": "html",
      "abTestVariant": "A",
      "weight": 50,
      "status": "active",
      "impression": 625,
      "click": 52,
      "dismiss": 20,
      "accept": 0,
      "convert": 18,
      "total": 715,
      "ctr": 8.32,
      "cvr": 2.88
    }
  ],
  "total": 8,
  "limit": 100,
  "offset": 0
}
```

### Response -- `groupBy=channel`

```json theme={null}
{
  "groupBy": "channel",
  "days": 30,
  "summary": [
    {
      "id": "ch_001",
      "name": "Marketing Email",
      "channelType": "email",
      "treatmentCount": 6,
      "impression": 2500,
      "click": 175,
      "dismiss": 90,
      "accept": 0,
      "convert": 0,
      "total": 2765,
      "ctr": 7.0
    }
  ],
  "total": 4,
  "limit": 100,
  "offset": 0
}
```

### Response -- `groupBy=customer`

Returns top customers by total interactions.

```json theme={null}
{
  "groupBy": "customer",
  "days": 30,
  "summary": [
    {
      "customerId": "C-1234",
      "total": 42,
      "impression": 20,
      "click": 8,
      "dismiss": 4,
      "accept": 0,
      "convert": 3,
      "uniqueActions": 5
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}
```

### Period resolution (materialized path)

When using materialized summaries, the `days` parameter maps to a period type:

| Days | Period Type |
| ---- | ----------- |
| 1    | `daily`     |
| 2-7  | `weekly`    |
| 8-31 | `monthly`   |
| 32+  | `alltime`   |

***

## Role requirements

| Method | Minimum role |
| ------ | ------------ |
| GET    | `viewer`     |