Skip to main content

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.

​
POST /api/v1/simulate

Run a simulation against a customer segment to preview how a Decision Flow would perform. Creates a SimulationRun record for tracking. Supports A/B comparison mode. Rate limit: 20 requests/min (expensive compute). Timeout: 120 seconds.

​
Request Body

FieldTypeRequiredDescription
segmentIdstringYesSegment to simulate against
decisionFlowKeystringNoDecision Flow key to simulate
blueprintKeystringNoAlias for decisionFlowKey
sampleSizenumberNoNumber of customers to sample (default: 1000)
channelFilterstringNoChannel filter (e.g., "email", "sms")
formulaOverrideobjectNoOverride formula values during simulation
compareobjectNoIf 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 a SimulationRun record with the simulation results merged in. 
{
  "id": "simrun_abc123",
  "status": "completed",
  "reachableCustomers": 487,
  "offersDelivered": 1204,
  "averageScore": 0.71,
  "topOffers": [
    { "offerId": "offer_premium_card", "count": 312 }
  ]
}
On failure, the run status is set to "failed" and a 500 error is returned.

​
GET /api/v1/simulate

List past simulation runs for the tenant. Supports pagination.

​
Query Parameters

ParameterTypeDefaultDescription
limitinteger20Max results per page (max 100)
offsetinteger0Number 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.