> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Running Simulations
> Trigger runs, watch them live, and read the settled report
A **run** is one execution of a simulation plan. Every run gets a sequential label (`SR-42`), a trigger chip showing how it started, and a run detail page that acts as mission control while calls are in flight — then settles into a full report once the last call lands.
Runs execute a configured plan — agent targets, customer flows, metrics, and run settings. If you haven't built one yet, start with [Run Plans](/documentation/simulation-testing/run-plans).
## Ways to trigger a run
Every run row carries a trigger chip telling you how it started:
| Trigger | How it happens |
| :----------- | :------------------------------------------------------------------------------------------------ |
| **Manual** | You clicked **Run simulation** on the create-run page, or **Run now** on a plan |
| **Schedule** | A recurring or one-time schedule fired ([Schedules](/documentation/simulation-testing/schedules)) |
| **Re-run** | Started from a previous run's **Re-run** menu |
| **System** | Roark started the run automatically |
### Run now
From **Simulate → Simulations**, click **New Run**, configure the run, and hit **Run simulation**. The split button's menu also offers **Schedule recurring…** and **Run once, later…** if you'd rather not run immediately. Tick **Save as plan** if you want to keep the configuration — otherwise the run is grouped under the **One-off runs** card on the runs hub.
To run an existing plan, open it and click **Run now**.
If your plan has {'{{variables}}'} without default values, a modal collects them before the run starts. See [Variables](/documentation/simulation-testing/variables).
### Via API
Trigger a plan programmatically and pass runtime variables:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST "https://api.roark.ai/v1/simulation/plan/{planId}/job" \
-H "Authorization: Bearer $ROARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"variables": {
"orderNumber": "12345",
"environment": "staging"
}
}'
```
The response includes the `simulationRunPlanJobId` you can poll via `GET /v1/simulation/plan/job/{jobId}`.
The REST API keeps the older naming: customer flows are called `scenarios`, so flow-scoped runtime variables are passed as an array of `{ scenarioId, variables }` objects.
## Run statuses
Runs show one of five statuses:
| Status | Meaning |
| :------------ | :-------------------------------------------------------- |
| **Queued** | Accepted and waiting to start |
| **Running** | Building test calls, executing them, or compiling results |
| **Completed** | Every call finished and the report is ready |
| **Failed** | The run hit an unrecoverable error or timed out |
| **Cancelled** | You cancelled the run before it finished |
The API exposes finer-grained backend statuses (`CREATING_SNAPSHOTS`, `CREATING_SIMULATIONS`, `RUNNING_SIMULATIONS`, `ENDING_SIMULATIONS`, `CANCELLING`) — all of these render as **Running** in the UI, and `TIMED_OUT` renders as **Failed**.
## Watching a live run
Open a run while it's executing and you get mission control. The header shows the plan name (or "One-off run #N"), the SR-number, Inbound/Outbound and template badges, the agents under test, and a pulsing **Running · mm:ss** clock. Banners walk you through the phases: "Starting the run", then "All calls landed — compiling the report".
* **Progress strip** — how many calls are done, in flight, and still queued.
* **Live now board** — every active conversation. Voice calls (Phone, WebRTC, LiveKit) stream audio so you can listen in as they happen; chat sessions (WebSocket, ElevenLabs, Google CES, Kore) show a live transcript instead. Pending conversations show their state: Dialing, Connecting, or Waiting for call.
* **What we're measuring** — the run's checks, so you know what pass/fail will be judged on.
* **Calls table** — click any call to open a split detail pane with the transcript, agent expectations, and audio for voice calls.
### Cancelling a run
Click the red **Cancel run** button in the header. Cancellation is graceful: **queued calls stop, but in-flight calls run to completion** and still appear in the results. The run settles with status **Cancelled**.
## The settled report
Once every call lands, the page becomes a report with four sections:
| Section | What's in it |
| :------------- | :-------------------------------------------------------- |
| **Overview** | Verdict hero and headline stats |
| **Metrics** | Per-metric results across the run |
| **Comparison** | This run side by side with the plan's other runs |
| **Calls** | Every conversation, with transcripts and per-call results |
The verdict hero leads with a check pass-rate ring and a plain-language narrative ("Clean sweep — every check passed on every conversation."), backed by stat cards: **Clean calls**, **Calls run**, and **Trend** or **Weakest check**.
Use the **Export** button to download the run's results as a CSV. A run-name dropdown in the header switches between the plan's executions (the newest is tagged "Latest") — or open the **Comparison** tab to view runs side by side.
## Re-running
The settled report's **Re-run** menu offers two distinct modes:
| Mode | What it does | Use it when |
| :------------------------ | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
| **Fresh run** | Builds new test calls from the plan **as configured today**, collecting any unresolved variables first | You've edited the plan or flows and want to test the current configuration |
| **Re-run with same data** | Replays this run's **exact snapshot** — same flows, personas, and settings, even if the plan has changed since | You want an apples-to-apples comparison, e.g. verifying a bug fix under identical conditions |
Re-runs land in the same plan's run history, so the Comparison tab picks them up automatically.
## Iterations and concurrency
Set in the plan's **Advanced → Run settings**:
* **Iterations** — runs per test case, up to 100. Useful for catching intermittent failures. Outbound runs are limited to 1 iteration — see [Inbound vs Outbound](/documentation/simulation-testing/inbound-vs-outbound).
* **Concurrency** — parallel calls. The default is 5, capped by your account quota. Start there and raise it once you've confirmed your agent handles the load.
## Next steps
Build reusable test suites
Put plans on a cadence
Parameterize flows with runtime values
Score metrics from your agent's side of the call