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

# Reach Estimate

> Estimate how many customers qualify or are excluded by a proposed qualification rule, with field distribution statistics.

## POST /api/v1/qualification-rules/reach-estimate

Estimates the impact of a proposed qualification rule by querying the actual customer data in a schema table. Returns qualifying/excluded counts, field distribution statistics, and a breakdown by segment.

### Request Body

| Field        | Type                              | Required | Description                                          |
| ------------ | --------------------------------- | -------- | ---------------------------------------------------- |
| `ruleType`   | string                            | Yes      | Rule type identifier                                 |
| `field`      | string                            | Yes      | Field name to evaluate (e.g., `age`, `credit_score`) |
| `operator`   | string                            | Yes      | Comparison operator (see table below)                |
| `value`      | string, number, boolean, or array | Yes      | Value to compare against                             |
| `schema`     | string                            | Yes      | Schema name containing the customer data             |
| `sampleSize` | integer                           | No       | Max rows to sample (100-10000, default: 1000)        |

### Supported Operators

| Operator       | SQL Equivalent | Description             |
| -------------- | -------------- | ----------------------- |
| `eq`           | `=`            | Equals                  |
| `neq`          | `!=`           | Not equals              |
| `gt`           | `>`            | Greater than            |
| `gte`          | `>=`           | Greater than or equal   |
| `lt`           | `<`            | Less than               |
| `lte`          | `<=`           | Less than or equal      |
| `in`           | SQL `in`       | Value in array          |
| `not_in`       | SQL `not in`   | Value not in array      |
| `contains`     | SQL `like`     | String contains         |
| `not_contains` | SQL `not like` | String does not contain |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/qualification-rules/reach-estimate \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "ruleType": "attribute_condition",
    "field": "credit_score",
    "operator": "gte",
    "value": 720,
    "schema": "customers",
    "sampleSize": 5000
  }'
```

### Response

```json theme={null}
{
  "totalSampled": 5000,
  "qualifying": 3250,
  "excluded": 1750,
  "qualifyPercent": 65.0,
  "excludedBySegment": [
    { "segment": "New Customers", "excluded": 820 },
    { "segment": "Low Risk", "excluded": 430 }
  ],
  "fieldDistribution": {
    "min": 300,
    "max": 850,
    "avg": 695.42,
    "median": 710,
    "p25": 620,
    "p75": 760
  }
}
```

### Response Fields

| Field               | Type           | Description                                                                   |
| ------------------- | -------------- | ----------------------------------------------------------------------------- |
| `totalSampled`      | integer        | Number of rows sampled                                                        |
| `qualifying`        | integer        | Rows matching the condition                                                   |
| `excluded`          | integer        | Rows not matching the condition                                               |
| `qualifyPercent`    | number         | Percentage of qualifying rows                                                 |
| `excludedBySegment` | array          | Breakdown of excluded customers by segment (if segments exist)                |
| `fieldDistribution` | object or null | Statistical distribution for numeric fields (min, max, avg, median, p25, p75) |

<Note>
  Field distribution statistics are only available for numeric fields. For text fields, `fieldDistribution` is `null`.
</Note>

### Roles

admin, editor

See also: [Qualification Rules](/api-reference/qualification-rules)