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

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

{
  "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)

Field distribution statistics are only available for numeric fields. For text fields, fieldDistribution is null.

Roles

admin, editor

See also: Qualification Rules