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

# Create a run plan

`POST /v1/simulation/plan`

Creates a new simulation run plan.

To run a simulation, use POST /v1/simulation/run instead: it starts a run from a plan or
from an inline configuration, and takes runtime variables. Create a plan here when you want
a reusable, named one to run later.

## Request body

- CreateRunPlanInput — Input for creating a new simulation run plan
  - `name` string, required — Name of the run plan
  - `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.
    - `conversationSource` 'SIMULATED' | 'LIVE', nullable — Which side of an enriched run this metric is scored on. Only meaningful with `enrichWithLiveConversation: true`, where a run has both a simulated conversation and the customer's own live recording of it. Defaults to `SIMULATED`. Use `LIVE` for a metric that must be measured against the real recording (audio quality, provider latency) rather than the simulated leg. `null` means the same as omitting it, so a plan read back from GET can be sent straight to PUT.
  - `enrichWithLiveConversation` boolean — Merge the customer's own recording of the real call into each simulation, so metrics can be scored against the live leg as well as the simulated one. This is the API equivalent of the dashboard's live-enrichment toggle. With this on, the run provisions a phone number and holds each call open for up to 15 minutes waiting for a matching call to be posted to POST /v1/call. A call matches on the provisioned number (`roarkPhoneNumber` on the job) with a start time inside the simulation window. If nothing arrives, the simulation still completes and any `LIVE`-sourced metric produces no value. Required by any metric whose `requiresLiveConversation` is true: without it that metric is silently skipped.
  - `autoRun` boolean — Deprecated: use POST /v1/simulation/run, which starts a run and accepts runtime `variables` as well. This flag runs the plan with only the values pinned on it.

## Response `201`

The created run plan

- object
  - `data` CreateRunPlanResponse, required — Response when creating a run plan, optionally including a triggered job
    - `runPlan` RunPlanResponse, required — A simulation run plan defining the test matrix
      - `id` string, uuid, required — Unique identifier of the run plan
      - `name` string, required — Name of the run plan
      - `description` string, nullable — Description of the run plan
      - `direction` 'INBOUND' | 'OUTBOUND', required — Direction of the simulation (INBOUND or OUTBOUND)
      - `iterationCount` integer, required — Number of iterations to run for each test case
      - `maxConcurrentJobs` integer, required — Maximum number of concurrent simulation jobs
      - `maxSimulationDurationSeconds` integer, required — Maximum duration in seconds for each simulation
      - `silenceTimeoutSeconds` integer, required — Timeout in seconds for silence detection
      - `endCallPhrases` string[], required — Phrases that trigger end of call. Empty array means disabled.
      - `endCallReasons` string[], required — Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array means disabled.
      - `executionMode` 'PARALLEL' | 'SEQUENTIAL_SAME_RUN_PLAN' | 'SEQUENTIAL_PROJECT', required — Execution mode (PARALLEL or SEQUENTIAL)
      - `scenarios` object[], required — Deprecated: use `flows` instead. Scenarios included in this run plan.
        - `id` string, uuid, required
        - `variables` object — Template variables for this scenario instance. Absent when no variables are set. The same scenario can appear multiple times with different variables.
      - `flows` RunPlanFlowSelection[], required — Customer flows included in this run plan
        - `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[], required — Personas included in this run plan. Only meaningful alongside `scenarios`.
        - `id` string, uuid, required
      - `agentEndpoints` object[], required — Agent endpoints included in this run plan
        - `id` string, uuid, required
      - `evaluators` object[], required — Deprecated: Use metrics instead. Evaluators included in this run plan.
        - `id` string, uuid, required
      - `metrics` object[], required — Metric definitions included in this run plan
        - `id` string, uuid, required
        - `conversationSource` 'SIMULATED' | 'LIVE', nullable, required — Which side of an enriched run this metric is scored on. `null` means the default, SIMULATED.
      - `enrichWithLiveConversation` boolean, required — Whether this plan merges the customer's own live recording into each simulation.
      - `testCaseCount` integer, required — Total number of test cases generated from the plan configuration
      - `createdAt` string, required — When the run plan was created
      - `updatedAt` string, required — When the run plan was last updated
    - `runPlanJob` RunSimulationPlanResponse — Response when triggering a simulation run plan
      - `simulationRunPlanId` string, uuid, required — ID of the simulation run plan that was executed
      - `simulationRunPlanJobId` string, uuid, required — ID of the simulation run plan job that was created
      - `status` 'PENDING' | 'QUEUED' | 'CREATING_SNAPSHOTS' | 'CREATING_SIMULATIONS' | 'PREPARING_CAPACITY' | 'RUNNING_SIMULATIONS' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'CANCELLING' | 'ENDING_SIMULATIONS', required — Initial status of the job
      - `createdAt` string, required — When the job was created

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-09-03** `6a09e09bd1ca` — 4 info
  - added the new optional request property `enrichWithLiveConversation`
  - added the new optional request property `metrics/items/conversationSource`
  - added the required property `data/runPlan/enrichWithLiveConversation` to the response with the `201` status
  - added the required property `data/runPlan/metrics/items/conversationSource` to the response with the `201` status
- **2026-08-20** `9080f2313118` — 1 warning
  - added the new `PREPARING_CAPACITY` enum value to the `data/runPlanJob/oneOf[#/components/schemas/RunSimulationPlanResponse]/status` response property for the response status `201`
- **2026-08-17** `887b091b3d81` — 11 warning, 10 info
  - the `iterationCount` request property's max was set to `10000.00`
  - added the new `conflict` enum value to the `type` response property for the response status `400`
  - added the new `conflict` enum value to the `type` response property for the response status `401`
  - added the new `conflict` enum value to the `type` response property for the response status `403`
  - …17 more
- **2026-04-20** `a1a7faf3a53b` — 1 info
  - added the optional property `data/runPlan/scenarios/items/variables` to the response with the `201` status

[Change history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/plan/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/de560a05f08a/schema)