---
title: "Run a simulation"
method: POST
path: "/v1/simulation/run"
tags: ["Simulation"]
---

# Run a simulation

`POST /v1/simulation/run`

Starts a simulation and returns the run.

Send `plan` to describe a simulation and run it once. Add `saveAsPlan` to keep that
configuration as a reusable run plan. Send `planId` instead to run a plan you already have.

## Request body

- union — Either a simulation to configure and run, or the id of a plan to run.
  - RunSimulationFromConfig — Describe a simulation and run it, optionally keeping the configuration as a reusable plan.
    - `plan` InlineRunPlanConfig, required — The simulation to run: what to call, who calls it, and what to measure.
      - `name` string — What to call this. Generated from the date when omitted, and required with `saveAsPlan`.
      - `description` string — Description of the run plan
      - `direction` 'INBOUND' | 'OUTBOUND', required — Direction of the simulation (INBOUND or OUTBOUND)
      - `iterationCount` integer — Number of iterations to run for each test case (1-10000)
      - `maxConcurrentJobs` integer — Maximum number of concurrent simulation jobs
      - `maxSimulationDurationSeconds` integer, required — Maximum duration in seconds for each simulation
      - `silenceTimeoutSeconds` integer — Timeout in seconds for silence detection
      - `endCallPhrases` string[] — Phrases that trigger end of call. Empty array disables the feature.
      - `endCallReasons` string[] — Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature.
      - `executionMode` 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT' — Execution mode (PARALLEL or SEQUENTIAL)
      - `scenarios` object[] — Deprecated: use `flows` instead. Scenarios to include in this run plan. The same scenario ID can appear multiple times with different variables.
        - `id` string, uuid, required — Scenario ID
        - `variables` object — Template variables for this scenario instance. The same scenario can appear multiple times with different variables.
      - `flows` RunPlanFlowSelection[] — Customer flows to include in this run plan. The same flow can appear more than once with a different persona override or different variables.
        - `id` string, uuid, required — The customer flow to run.
        - `happyPath` boolean — Run the flow's happy path. Resolved when the run starts, so it follows the flow.
        - `edgeCases` union — `"ALL"` runs every edge case the flow has when the run starts, so one added later is covered. An array runs only the ones you name, each able to carry its own persona override and values.
          - 'ALL'
          - RunPlanEdgeCaseSelection[]
            - `id` string, uuid, required — The edge case to run.
            - `personaOverrideId` string, uuid, nullable — Run this one as that persona instead of its own.
            - `variables` object — Values for this one only.
        - `personaOverrideId` string, uuid, nullable — Runs everything this attachment resolves as that persona instead of its own.
        - `variables` object — Values for everything it resolves.
      - `personas` object[] — Personas to include in this run plan. Required with `scenarios`; ignored with `flows`, where each variant carries its own persona.
        - `id` string, uuid, required
      - `agentEndpoints` object[], required — Agent endpoints to include in this run plan
        - `id` string, uuid, required
      - `metrics` RunPlanMetricRef[], required — Metric definitions to include in this run plan. Reference each by `id` (UUID) or `slug`.
        - `id` string, uuid — Metric definition UUID. Provide either this or `slug`, not both.
        - `slug` string — Stable metric slug (e.g. `customer_satisfaction`). Provide either this or `id`, not both.
        - `metricId` string — Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations.
    - `saveAsPlan` boolean — Keeps this configuration as a run plan, listed by GET /v1/simulation/plan and re-runnable with `planId`. Requires `plan.name`, since a plan you meant to keep should not be filed under a generated one. Omitted or false gives a one-off. The run still needs a plan to execute, so one is created either way, but it is hidden: it carries this run and nothing else.
    - `variables` union — Values for the {{variables}} the run resolves, overriding whatever the plan has pinned. An object applies them to the whole run: { "orderNumber": "12345", "tier": "gold" } An array applies them per flow, or to just its happy path or one of its edge cases, when a single set will not do. Each entry carries what it applies to: [ { "flowId": "550e8400-...", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-...", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-...", "edgeCaseId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ] An entry that narrows to neither covers everything that flow resolves. A flow this plan does not attach, or an edge case that does not belong to the flow, is rejected rather than ignored. A plan built on scenarios rather than customer flows targets them the same way, with `scenarioId` in place of `flowId`. That form is deprecated alongside scenarios themselves, and still accepted so runs against those plans keep working.
      - object — Global format: key-value pairs that apply to ALL scenarios in the plan
      - object[] — Values scoped to the flows this plan runs
        - `flowId` string, uuid, required — A customer flow this plan runs.
        - `happyPath` true — Narrow to the flow's happy path.
        - `edgeCaseId` string, uuid — Narrow to one edge case of that flow.
        - `variables` object, required — The values to apply.
      - object[] — Deprecated, for plans built on scenarios. Plans built on customer flows target them with `flowId` instead.
        - `scenarioId` string, uuid, required — ID of the scenario to apply variables to
        - `variables` object, required — Key-value pairs for this scenario
  - RunSimulationFromPlanId — Run a plan that already exists.
    - `planId` string, uuid, required — The run plan to run, saved or hidden. Rename or unhide it with PUT /v1/simulation/plan/{planId}.
    - `variables` union — Values for the {{variables}} the run resolves, overriding whatever the plan has pinned. An object applies them to the whole run: { "orderNumber": "12345", "tier": "gold" } An array applies them per flow, or to just its happy path or one of its edge cases, when a single set will not do. Each entry carries what it applies to: [ { "flowId": "550e8400-...", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-...", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-...", "edgeCaseId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ] An entry that narrows to neither covers everything that flow resolves. A flow this plan does not attach, or an edge case that does not belong to the flow, is rejected rather than ignored. A plan built on scenarios rather than customer flows targets them the same way, with `scenarioId` in place of `flowId`. That form is deprecated alongside scenarios themselves, and still accepted so runs against those plans keep working.
      - object — Global format: key-value pairs that apply to ALL scenarios in the plan
      - object[] — Values scoped to the flows this plan runs
        - `flowId` string, uuid, required — A customer flow this plan runs.
        - `happyPath` true — Narrow to the flow's happy path.
        - `edgeCaseId` string, uuid — Narrow to one edge case of that flow.
        - `variables` object, required — The values to apply.
      - object[] — Deprecated, for plans built on scenarios. Plans built on customer flows target them with `flowId` instead.
        - `scenarioId` string, uuid, required — ID of the scenario to apply variables to
        - `variables` object, required — Key-value pairs for this scenario

## Response `200`

The run that was started

- object
  - `data` RunSimulationResponse, required — A started simulation run.
    - `simulationRunPlanJobId` string, uuid, required — The run. Poll it with GET /v1/simulation/plan/job/{jobId}.
    - `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS', required — Initial status. PENDING normally, or QUEUED when the plan runs sequentially and another job of its is still active.
    - `createdAt` string, required — When the run was created, ISO 8601.
    - `simulationRunPlanId` string, uuid, required — The run plan behind this run, present whether or not it was saved. Pass it back as `planId` to run the same configuration again.
    - `savedAsPlan` boolean, required — Whether that plan is listed by GET /v1/simulation/plan. False for an unsaved run, whose plan is hidden.
    - `simulationJobCount` integer, required — How many simulated calls this run places.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-08-20** `9080f2313118` — 1 warning
  - added the new `PREPARING_CAPACITY` enum value to the `data/status` response property for the response status `200`
- **2026-08-17** `887b091b3d81` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/run/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) · [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/revisions/1d61b68e9429/schema)