> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate Sequence

> Preview who a sequence would enroll and one contact's path, without sending mail

# Simulate Sequence

Dry-run a sequence. Nothing is sent, no one is enrolled, and tags, lists, and discounts are not written.

Activating a sequence does **not** enroll anyone automatically. Without a subscriber this reports who currently matches and whether the sequence is ready (existing list, tag, and segment matches can still be enrolled by hand).

Pass `subscriberId` or `email` to also walk that stored contact through the graph and see which branch they take. Use that to check cases like "would a paid user get the upgrade email?"

Call this before [Enable Sequence](/api-reference/sequences/enable).

<Note>
  `sendsMail` is always `false`. To send one saved email step to a reviewer, use
  [Send Sequence Step Test](/api-reference/sequences/send-test).
</Note>

<Note>
  This endpoint always requires both `sequences:read` and `subscribers:read`
  because aggregate results include contact samples, even when no subscriber is
  selected for a path preview.
</Note>

## Request

<ParamField path="sequenceId" type="string" required>
  Sequence ID.
</ParamField>

<ParamField query="subscriberId" type="string">
  Optional stored subscriber to walk through the graph. Do not pass with
  `email`.
</ParamField>

<ParamField query="email" type="string">
  Optional stored subscriber email to walk through the graph. Do not pass with
  `subscriberId`.
</ParamField>

<ParamField query="limit" type="integer">
  How many currently matching contacts to include in the sample. Defaults to 10,
  maximum 25.
</ParamField>

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/sequences/seq_abc123/simulate" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/sequences/seq_abc123/simulate?email=maya@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response fields

<ResponseField name="sendsMail" type="boolean">
  Always `false`.
</ResponseField>

<ResponseField name="enrollment.summary" type="string">
  Plain-language description of who enrolls after activation.
</ResponseField>

<ResponseField name="enrollment.currentlyMatchingAvailable" type="boolean">
  Whether an exact current-match count is available. This is `false` for
  frequency and inactivity triggers, whose matches are evaluated by the hourly
  worker.
</ResponseField>

<ResponseField name="enrollment.autoEnrollOnActivateCount" type="number">
  Always `0`. Activating a sequence does not enroll anyone.
</ResponseField>

<ResponseField name="enrollment.currentlyMatchingCount" type="number | null">
  Contacts who match the trigger right now and are not already in the sequence.
  These people are not auto-enrolled. `null` when `currentlyMatchingAvailable`
  is `false`.
</ResponseField>

<ResponseField name="readiness.ready" type="boolean">
  `false` when activation blockers are present (missing trigger, unattached
  email, disconnected discount provider, and similar).
</ResponseField>

<ResponseField name="path" type="object">
  Walked graph for the optional stored subscriber, or `null` when none was
  passed. Each step may include an `outcome` with `verdict` (`passed`, `failed`,
  or `unknown`) and `assumed` when the branch could not be known statically.
</ResponseField>

<ResponseField name="path.emailStepsOnPath" type="number">
  Email and A/B-test steps traversed by the selected path, whether or not the
  subscriber can currently receive them.
</ResponseField>

<ResponseField name="path.emailsOnPath" type="number">
  Traversed email steps deliverable for the subscriber's current email and
  subscription status. Transactional steps remain deliverable to unsubscribed
  contacts; bounced and email-less contacts have no deliverable emails.
</ResponseField>

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "sequenceId": "seq_abc123",
    "sequenceName": "Trial upgrade",
    "status": "draft",
    "sendsMail": false,
    "enrollment": {
      "triggerType": "tag_added",
      "summary": "Anyone who gets the \"trial\" tag from now on goes through this sequence.",
      "note": "The 2 people who already have the tag won't be enrolled automatically - you can enroll them manually later.",
      "autoEnrollOnActivateCount": 0,
      "autoEnrollTiming": "on_future_match",
      "currentlyMatchingCount": 2,
      "currentlyMatchingEnrollsAutomatically": false,
      "currentlyMatchingSample": [
        { "id": "sub_1", "email": "maya@example.com", "name": "Maya" }
      ],
      "error": null
    },
    "readiness": {
      "ready": true,
      "errors": [],
      "warnings": []
    },
    "path": null
  }
  ```
</ResponseExample>