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

# Segment Overlap

> Analyze customer overlap between multiple segments to identify redundancy and optimize targeting.

## POST /api/v1/segments/overlap

Computes pairwise overlap between 2-10 segments by querying their underlying PostgreSQL views. Returns overlap counts, percentages, and warnings for high-overlap pairs.

### Request Body

| Field        | Type      | Required | Description                                                    |
| ------------ | --------- | -------- | -------------------------------------------------------------- |
| `segmentIds` | string\[] | Yes      | Array of 2-10 segment IDs to compare                           |
| `sampleSize` | integer   | No       | Max customers per segment to sample (100-50000, default: 5000) |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/segments/overlap \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "segmentIds": ["seg_001", "seg_002", "seg_003"],
    "sampleSize": 10000
  }'
```

### Response

```json theme={null}
{
  "segments": [
    { "id": "seg_001", "name": "High Value", "size": 4200 },
    { "id": "seg_002", "name": "Active Traders", "size": 3100 },
    { "id": "seg_003", "name": "Premium Tier", "size": 1800 }
  ],
  "overlaps": [
    { "segments": ["seg_001", "seg_002"], "count": 1250, "percent": 40 },
    { "segments": ["seg_001", "seg_003"], "count": 1100, "percent": 61 },
    { "segments": ["seg_002", "seg_003"], "count": 680, "percent": 38 }
  ],
  "totalUniqueCustomers": 6170,
  "overlapWarnings": [
    "61% of Premium Tier customers are also in High Value — consider merging or adjusting targeting",
    "40% of Active Traders customers are also in High Value — consider merging or adjusting targeting",
    "38% of Premium Tier customers are also in Active Traders — consider merging or adjusting targeting"
  ]
}
```

### Response Fields

| Field                  | Type      | Description                                  |
| ---------------------- | --------- | -------------------------------------------- |
| `segments`             | array     | Each segment's ID, name, and sampled size    |
| `overlaps`             | array     | Pairwise overlap results                     |
| `overlaps[].segments`  | string\[] | Pair of segment IDs                          |
| `overlaps[].count`     | integer   | Number of shared customers                   |
| `overlaps[].percent`   | integer   | Overlap as percentage of the smaller segment |
| `totalUniqueCustomers` | integer   | Distinct customers across all segments       |
| `overlapWarnings`      | string\[] | Warnings when overlap is 30% or higher       |

### Error Codes

| Code  | Reason                                                |
| ----- | ----------------------------------------------------- |
| `400` | Fewer than 2 or more than 10 segment IDs              |
| `400` | Segment not found or segment has no materialized view |

### Roles

admin, editor, viewer

See also: [Segments](/api-reference/segments)