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

# Simulate

> Simulate a Recommend API call against a Decision Flow to preview results without recording outcomes or traces.

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

```bash theme={null}
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.

```json theme={null}
{
  "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

| Parameter | Type    | Default | Description                    |
| --------- | ------- | ------- | ------------------------------ |
| `limit`   | integer | `20`    | Max results per page (max 100) |
| `offset`  | integer | `0`     | Number of records to skip      |

### Response

```json theme={null}
{
  "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

<Tip>
  Use the Simulate API during development and testing to validate Decision Flow configurations without polluting production interaction history.
</Tip>