# Preview a contact's journey step path without sending

`POST /v1/journeys/{id}/simulate`

Requires an API key with the `journeys:read` scope. [About keys and scopes](/docs/api/authentication)

Previews a run without sending. `entry` says whether the contact would enter now: a date journey needs a valid date in its field; an event journey checks the supplied eventProperties against the entry conditions, then reentry. The path follows branches on eventProperties and filters and splits on the contact as they are now; a wait-until step takes its match path. Each send step is checked against suppression, consent, topics and devices: `would_send`, `unreachable` (takes the fallback path) or `would_skip`, with the refusal code in `reason` (`DRAFT_INCOMPLETE` for a send step not yet finished: a draft simulates too). Message limits and send-time scheduling are not previewed.

## Path parameters

- `id` (string, required, uuid)

## Request body

- `contactId` (string, required, uuid) — The contact to simulate.
- `eventProperties` (object, optional, default `{}`) — Properties of a trigger event to simulate, checked against entry conditions.

## Returns

Returns `200 OK`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `contactId` (string, required, uuid)
- `entry` (object, required) — Whether the contact would enter the journey now.
  - `eligible` (boolean, required) — Whether the contact would enter now.
  - `reason` (string | null, required) — Why not: `no_date`, `entry_conditions_not_met`, `already_enrolled` or `in_cooldown`.
- `path` (object[], required) — The steps the contact would pass through, in order.
  - `stepIndex` (integer, required, min -9007199254740991, max 9007199254740991) — Index of the step in `steps`.
  - `type` (string, required) — The step type.
  - `outcome` (string, required) — What the step would do.
  - `reason` (string, optional) — Why a send step would not send: the send guard's error code.

## Example

```bash
curl -X POST https://api.kirora.io/v1/journeys/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/simulate \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "018f2a4e-6b1c-7d3e-9f40-4db757ce5a6b"
  }'
```

Response `200`:

```json
{
  "data": {
    "contactId": "018f2a4e-6b1c-7d3e-9f40-4db757ce5a6b",
    "entry": {
      "eligible": true,
      "reason": "reason_example"
    },
    "path": [
      {
        "stepIndex": -9007199254740991,
        "type": "type_example",
        "outcome": "outcome_example"
      }
    ]
  }
}
```