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

# Creative Uplift Signal

> Per-creative observational uplift — treatment vs. holdout conversion deltas for every creative on an offer, without running an experiment.

## GET /api/v1/treatments/uplift

Returns a per-creative uplift micro-card for every creative on a given offer (or every creative across the tenant's active offers when `offerId` is omitted). For each creative, the customers who saw **that** creative form the treatment cohort; customers who saw the same offer through a **different** creative form the comparison cohort. Conversion deltas are evaluated with the same two-proportion z-test used by Experiments.

<Warning>
  This is an **observational** signal, not a randomized controlled trial. Creative assignment is not randomized here, so the deltas are directional reads for the Studio treatments page — use the [Experiments API](/api-reference/experiments) with holdout groups when you need causally rigorous uplift.
</Warning>

### Query Parameters

| Parameter    | Type   | Required | Description                                                                           |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------- |
| `offerId`    | string | No       | Limit to one offer. When omitted, scans up to 200 active offers.                      |
| `windowDays` | number | No       | Lookback window for interactions (1-180, default: 30)                                 |
| `minSamples` | number | No       | Impression threshold below which a card is marked `samplesBelowMinimum` (default: 50) |

### Example

```bash theme={null}
curl "https://playground.kaireonai.com/api/v1/treatments/uplift?offerId=offer_123&windowDays=30" \
  -H "X-API-Key: your-api-key" \
  -H "X-Tenant-Id: my-tenant"
```

### Response

```json theme={null}
{
  "tenantId": "5a9904b9-...",
  "windowDays": 30,
  "minSamples": 50,
  "offerCount": 1,
  "cards": [
    {
      "offerId": "offer_123",
      "offerName": "Gold Credit Card",
      "creativeId": "creative_456",
      "samples": 240,
      "samplesBelowMinimum": false,
      "treatmentConversionRate": 0.125,
      "holdoutConversionRate": 0.081,
      "uplift": 0.044,
      "relativeUplift": 0.5432,
      "zScore": 2.11,
      "pValue": 0.0349,
      "significant": true,
      "treatmentSamples": 240,
      "holdoutSamples": 612,
      "ciLower": 0.003,
      "ciUpper": 0.085,
      "insufficientData": false
    }
  ]
}
```

Each card spreads the full uplift result: `treatmentConversionRate`, `holdoutConversionRate`, `uplift` (absolute), `relativeUplift`, `zScore`, `pValue`, `significant`, `treatmentSamples`, `holdoutSamples`, `ciLower`/`ciUpper` (95% CI, `null` when data is insufficient), and `insufficientData`. Cards whose treatment impressions fall below `minSamples` are still returned, flagged with `samplesBelowMinimum: true`.

### Roles

| Endpoint                 | Allowed roles            |
| ------------------------ | ------------------------ |
| `GET /treatments/uplift` | Any authenticated caller |