---
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.
  - `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
      - `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-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/1d61b68e9429/schema)