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

# Attribution

> Compute and query multi-touch attribution for customer conversions.

The Attribution API computes credit assignment across touchpoints that led to a conversion. Supports six attribution models.

## POST /api/v1/attribution

Compute attribution for a customer conversion. Rate limited to 100 requests/min. **Editor or Admin.**

### Request Body

| Field             | Type   | Required | Description                                   |
| ----------------- | ------ | -------- | --------------------------------------------- |
| `customerId`      | string | Yes      | Customer identifier                           |
| `conversionId`    | string | Yes      | Unique conversion event ID                    |
| `model`           | string | No       | Attribution model (default: `linear`)         |
| `conversionValue` | number | No       | Monetary value of the conversion (default: 1) |

### Attribution Models

| Model            | Description                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `last_touch`     | 100% credit to the last touchpoint before conversion                                                                                                                                                                                                                                                                                                                                      |
| `first_touch`    | 100% credit to the first touchpoint                                                                                                                                                                                                                                                                                                                                                       |
| `linear`         | Equal credit distributed across all touchpoints                                                                                                                                                                                                                                                                                                                                           |
| `time_decay`     | More credit to touchpoints closer to conversion                                                                                                                                                                                                                                                                                                                                           |
| `position_based` | 40% to first, 40% to last, 20% distributed across middle                                                                                                                                                                                                                                                                                                                                  |
| `shapley`        | Game-theoretic credit assignment — each touchpoint's Shapley value is its average marginal contribution across all coalitions of the other touchpoints, using a submodular (diminishing-returns) coalition-value function so credits are not just a linear split. Exact computation for ≤8 touchpoints (enumerates all 2^n subsets); a 1,000-sample Monte Carlo approximation above that. |

<Info>
  `model` accepts exactly `last_touch`, `first_touch`, `linear`, `time_decay`, `position_based`, or `shapley` — an unrecognized value returns `400` with `{ "error": "model must be one of: ..." }` (same validation on GET, see below).
</Info>

<Warning>
  **The touchpoint window is anchored on the conversion, not "now."** `computeAttribution` fetches the 100 `InteractionHistory` rows immediately preceding (and including) the conversion event, ordered by timestamp descending from the conversion's own timestamp — not from the current time. For a customer with more than 100 interactions total, anchoring on "now" previously meant a conversion that happened earlier in that history could fall outside the 100-row window and be silently excluded from its own attribution chain. Anchoring on the conversion's timestamp guarantees the conversion (and its preceding touchpoints, up to the 100-row cap) are always included.
</Warning>

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/attribution \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "customerId": "C-1234",
    "conversionId": "conv_abc123",
    "model": "time_decay",
    "conversionValue": 99.99
  }'
```

### Response (201)

```json theme={null}
{
  "customerId": "C-1234",
  "conversionId": "conv_abc123",
  "model": "time_decay",
  "totalValue": 99.99,
  "touchpoints": [
    { "offerId": "offer_1", "channelId": "ch_email", "credit": 0.15, "value": 14.99 },
    { "offerId": "offer_2", "channelId": "ch_push", "credit": 0.35, "value": 35.00 },
    { "offerId": "offer_1", "channelId": "ch_sms", "credit": 0.50, "value": 50.00 }
  ]
}
```

***

## GET /api/v1/attribution

Query attribution results. **Editor or Admin.**

### Query Parameters

| Parameter    | Type   | Required | Description                                                                                                          |
| ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `customerId` | string | No       | Filter by customer                                                                                                   |
| `model`      | string | No       | Filter by attribution model. One of `last_touch`, `first_touch`, `linear`, `time_decay`, `position_based`, `shapley` |
| `limit`      | number | No       | Max results (default: 50, max: 200)                                                                                  |
| `offset`     | number | No       | Pagination offset                                                                                                    |

An unrecognized `model` value returns `400` with `{ "error": "model must be one of: ..." }` — the same validation the POST endpoint applies.

### Response

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
```