POST /api/v1/simulate
Run a simulation against a customer segment to preview how a Decision Flow would perform. Creates a simulation-run record for tracking. Supports A/B comparison mode.
Rate limit: 20 requests/min (expensive compute). Timeout: 120 seconds.
Request Body
| Field | Type | Required | Description |
|---|
segmentId | string | Yes | Segment to simulate against |
decisionFlowKey | string | No | Decision Flow key to simulate |
blueprintKey | string | No | Alias for decisionFlowKey |
sampleSize | number | No | Number of customers to sample (default: 1000) |
channelFilter | string | No | Channel filter (e.g., "email", "sms") |
formulaOverride | object | No | Override formula values during simulation |
compare | object | No | If provided, runs A/B comparison mode (see below) |
Compare Mode
When compare is provided, the API runs two simulations side-by-side: scenario A uses the top-level config, and scenario B merges the compare object with segmentId. The response contains both results for comparison.
Example
curl -X POST https://playground.kaireonai.com/api/v1/simulate \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"segmentId": "seg_premium_customers",
"decisionFlowKey": "credit-cards",
"sampleSize": 500,
"channelFilter": "email"
}'
Response
Returns the simulation-run record with the results merged in.
{
"id": "simrun_abc123",
"status": "completed",
"reachableCustomers": 487,
"offersDelivered": 1204,
"averageScore": 0.71,
"topOffers": [
{ "offerId": "offer_premium_card", "count": 312 }
]
}
"failed" and a 500 error is returned.
GET /api/v1/simulate
List past simulation runs for the tenant. Supports pagination.
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 20 | Max results per page (max 100) |
offset | integer | 0 | Number of records to skip |
Response
{
"data": [
{
"id": "simrun_abc123",
"segmentId": "seg_premium_customers",
"decisionFlowKey": "credit-cards",
"sampleSize": 500,
"status": "completed",
"config": { "segmentId": "seg_premium_customers", "sampleSize": 500 },
"results": { "reachableCustomers": 487 },
"createdAt": "2026-03-10T12:00:00.000Z",
"completedAt": "2026-03-10T12:00:15.000Z"
}
],
"pagination": {
"total": 12,
"limit": 20,
"offset": 0,
"hasMore": false
}
}
Roles
admin, editor
Use the Simulate API during development and testing to validate Decision Flow configurations without polluting production interaction history.
