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

> Query customer interaction records with filtering by customer, offer, creative, and interaction type.

The Interaction History API provides read access to the log of all customer interactions. Each record captures an offer presentation, click, acceptance, or other outcome. Results include the related offer and creative details.

## Base path

```
/api/v1/interaction-history
```

***

## Query interactions

```
GET /api/v1/interaction-history
```

Returns a paginated list of interaction records, ordered by timestamp (newest first). Supports cursor-based keyset pagination.

### Query parameters

| Parameter     | Required | Type    | Description                                                                               |
| ------------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
| `customerId`  | No       | string  | Filter by customer ID.                                                                    |
| `offerId`     | No       | string  | Filter by offer ID.                                                                       |
| `actionId`    | No       | string  | Legacy alias for `offerId`.                                                               |
| `creativeId`  | No       | string  | Filter by creative ID.                                                                    |
| `treatmentId` | No       | string  | Legacy alias for `creativeId`.                                                            |
| `type`        | No       | string  | Filter by interaction type (e.g., `impression`, `click`, `dismiss`, `convert`, `accept`). |
| `limit`       | No       | integer | Maximum results per page (default from pagination config).                                |
| `cursor`      | No       | string  | Cursor ID for keyset pagination (returns records with `id < cursor`).                     |

### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "ih_001",
      "tenantId": "t_001",
      "customerId": "CUST001",
      "offerId": "off_abc123",
      "creativeId": "cr_001",
      "channelId": "ch_email",
      "interactionType": "click",
      "outcomeTypeKey": "click",
      "direction": "outbound",
      "timestamp": "2026-03-15T14:30:00.000Z",
      "context": {},
      "response": {},
      "outcome": {},
      "offer": {
        "id": "off_abc123",
        "name": "Platinum Card Upgrade",
        "status": "active"
      },
      "creative": {
        "id": "cr_001",
        "name": "Email Hero Variant A",
        "channel": {
          "id": "ch_email",
          "name": "Email"
        }
      }
    }
  ],
  "pagination": {
    "total": 1500,
    "limit": 25,
    "hasMore": true,
    "cursor": "ih_xyz789"
  }
}
```

### Error codes

| Code  | Reason                             |
| ----- | ---------------------------------- |
| `401` | Missing or invalid authentication. |
| `403` | Insufficient role permissions.     |

***

## Role requirements

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

<Card title="Decision Traces" icon="magnifying-glass" href="/api-reference/decision-traces">
  For forensic decision pipeline analysis, see the Decision Traces API.
</Card>